Eureka Labo MCP Server

# Sub-Agent Integration Guide ## Overview EurekaClaude MCP Server now integrates with **Claude Code sub-agents** - specialized autonomous agents that handle complex, domain-specific tasks. This integration makes your task management workflow significantly more intelligent and automated. ## What are Sub-Agents? Sub-agents are specialist agents built into Claude Code that have deep expertise in specific domains: - **technical-writer**: Documentation, commit messages, PR descriptions - **system-architect**: System design, configuration, setup analysis - **devops-architect**: Infrastructure, deployment, validation - **quality-engineer**: Testing, validation, quality assurance - **security-engineer**: Security analysis and vulnerability detection - **performance-engineer**: Performance optimization and analysis - **pm-agent**: Project management, knowledge capture, documentation - **root-cause-analyst**: Systematic problem investigation - **requirements-analyst**: Requirements discovery and specification - **deep-research-agent**: Comprehensive research with adaptive strategies ## Available Sub-Agent Tools ### 1. `generate_smart_commit_message` **Purpose**: Analyze git changes and generate intelligent commit messages **Sub-Agent**: `technical-writer` **Use Case**: Automatically create professional commit messages following Conventional Commits format **Parameters**: ```typescript { gitDiff: string; // Git diff output to analyze taskContext?: object; // Optional task context for additional information } ``` **Example Usage**: ```typescript // When Claude Code processes this tool, it launches technical-writer sub-agent mcp__eureka-tasks__generate_smart_commit_message({ gitDiff: "diff --git a/src/auth.ts...", taskContext: { taskId: "task-123", title: "ユーザー認証機能の実装" } }) ``` **Output**: Ready-to-use commit message following project conventions **Integration Point**: Can be used in `complete_task_work` to auto-generate commit messages --- ### 2. `generate_smart_pr_description` **Purpose**: Generate comprehensive PR descriptions from branch tasks and changes **Sub-Agent**: `technical-writer` **Use Case**: Create professional, detailed PR descriptions automatically when creating pull requests **Parameters**: ```typescript { branchTasks: Array<Task>; // All tasks from the branch gitDiff: string; // Git diff summary for the branch baseBranch?: string; // Base branch name (default: 'main') } ``` **Example Usage**: ```typescript const branchTasks = await mcp__eureka-tasks__list_branch_tasks(); const gitDiff = await getGitDiffSummary(); mcp__eureka-tasks__generate_smart_pr_description({ branchTasks: branchTasks.tasks, gitDiff: gitDiff, baseBranch: "main" }) ``` **Output**: GitHub-ready markdown with: - Japanese summary (概要) - English detailed description - Testing checklist - Breaking changes section - Related task links **Integration Point**: Enhances `create_pull_request` with AI-generated descriptions --- ### 3. `validate_setup` **Purpose**: Comprehensively validate eurekaclaude installation and configuration **Sub-Agent**: `devops-architect` **Use Case**: Health check for the entire eurekaclaude system **Parameters**: ```typescript { projectPath?: string; // Project path to validate (defaults to workspace path) } ``` **Example Usage**: ```typescript mcp__eureka-tasks__validate_setup({ projectPath: "/path/to/project" }) ``` **Output**: Detailed validation report with: - ✅ Passing checks (environment, git, MCP config) - ⚠️ Warnings (non-critical issues) - ❌ Critical issues (blocking problems) - 🔧 Recommended actions (fix commands) - 📊 System information **Integration Point**: Great for troubleshooting and onboarding --- ### 4. `generate_smart_setup` **Purpose**: Analyze project and generate optimal eurekaclaude configuration **Sub-Agent**: `system-architect` **Use Case**: Intelligent setup assistant for new projects **Parameters**: ```typescript { projectPath?: string; // Project path to analyze (defaults to workspace) projectType?: string; // Optional type hint (react, vue, python, go, etc.) } ``` **Example Usage**: ```typescript mcp__eureka-tasks__generate_smart_setup({ projectPath: "/path/to/new/project", projectType: "react" }) ``` **Output**: Complete configuration package: - `claude_desktop_config.json` entry - Environment variable setup - Recommended git hooks - Task templates for project type - Step-by-step setup instructions **Integration Point**: Streamlines onboarding for new projects --- ## How Sub-Agent Tools Work ### Architecture ``` User/Claude Request ↓ EurekaClaude MCP Tool ↓ Generate Sub-Agent Prompt (subagent-helpers.ts) ↓ Return Sub-Agent Invocation Instructions ↓ Claude Code Reads Instructions ↓ Claude Code Launches Specialized Sub-Agent ↓ Sub-Agent Works Autonomously ↓ Sub-Agent Returns Results ↓ Results Flow Back to User ``` ### Sub-Agent Invocation Pattern When you call a sub-agent tool, the MCP server returns instructions for Claude Code: ```markdown 🤖 Launch Claude Code Sub-Agent Please use the Task tool to launch a specialized sub-agent: **Sub-Agent Type**: technical-writer **Task Description**: Generate intelligent commit message **Prompt**: [Detailed prompt with requirements and context] **Instructions**: 1. Use the Task tool with subagent_type="technical-writer" 2. Pass the prompt above 3. Return the sub-agent's response as the tool result 4. The sub-agent will work autonomously and return when complete ``` Claude Code automatically recognizes this pattern and launches the appropriate sub-agent. --- ## Integration Patterns ### Pattern 1: Enhanced Work Session Completion ```typescript // Automatic intelligent commit message generation async function completeTaskWork(taskId: string, summary: string) { // 1. Capture git changes const gitDiff = await captureGitChanges(); // 2. Generate smart commit message const commitMsgInvocation = await mcp.call('generate_smart_commit_message', { gitDiff, taskContext: { taskId, summary } }); // 3. Claude Code launches technical-writer sub-agent // 4. Sub-agent returns professional commit message // 5. Complete work session with AI-generated message return completeWork(taskId, summary); } ``` ### Pattern 2: Automated PR Creation ```typescript // Comprehensive PR generation with AI async function createPullRequest() { // 1. Get all branch tasks const branchTasks = await listBranchTasks(); // 2. Get git diff summary const gitDiff = await getGitDiffSummary(); // 3. Generate smart PR description const prDescriptionInvocation = await mcp.call('generate_smart_pr_description', { branchTasks, gitDiff, baseBranch: 'main' }); // 4. Claude Code launches technical-writer sub-agent // 5. Sub-agent generates comprehensive PR description // 6. Create PR with AI-generated description return createPR(prDescription); } ``` ### Pattern 3: Setup Validation Workflow ```typescript // Health check before important operations async function validateBeforeOperation() { // 1. Run validation const validationInvocation = await mcp.call('validate_setup', { projectPath: process.cwd() }); // 2. Claude Code launches devops-architect sub-agent // 3. Sub-agent performs comprehensive checks // 4. Review validation report if (validationReport.criticalIssues.length > 0) { throw new Error('Critical setup issues detected'); } // 5. Proceed with operation return performOperation(); } ``` ### Pattern 4: Intelligent Project Onboarding ```typescript // Smart setup for new projects async function onboardNewProject(projectPath: string) { // 1. Analyze project structure const setupInvocation = await mcp.call('generate_smart_setup', { projectPath, projectType: 'auto-detect' }); // 2. Claude Code launches system-architect sub-agent // 3. Sub-agent analyzes project and generates config // 4. Apply generated configuration await applyConfiguration(setupConfig); // 5. Install recommended hooks await installHooks(setupConfig.recommendedHooks); // 6. Create task templates await createTaskTemplates(setupConfig.taskTemplates); return { success: true, config: setupConfig }; } ``` --- ## CLI Integration The CLI tool can be enhanced to use these sub-agent tools: ### Enhanced `eurekaclaude pr create` ```typescript // cli/src/commands/pr.ts export async function createPR() { console.log('🤖 Generating intelligent PR description...'); // Call the smart PR description tool const result = await mcpClient.call('generate_smart_pr_description', { branchTasks: await getBranchTasks(), gitDiff: await getGitDiff() }); // Claude Code handles sub-agent invocation automatically // Result contains the AI-generated PR description await createGitHubPR(result.description); console.log('✅ PR created with AI-generated description!'); } ``` ### New `eurekaclaude validate` Command ```typescript // cli/src/commands/validate.ts export async function validate() { console.log('🔍 Running comprehensive validation...'); const result = await mcpClient.call('validate_setup', { projectPath: process.cwd() }); // Display validation report console.log(result.report); if (result.criticalIssues.length > 0) { console.error('❌ Critical issues detected!'); process.exit(1); } console.log('✅ Validation passed!'); } ``` ### New `eurekaclaude setup` Command ```typescript // cli/src/commands/setup.ts export async function smartSetup(options: SetupOptions) { console.log('🤖 Analyzing project and generating configuration...'); const result = await mcpClient.call('generate_smart_setup', { projectPath: process.cwd(), projectType: options.type }); // Apply configuration await applySetup(result.config); console.log('✅ Smart setup complete!'); console.log('\nNext steps:'); result.config.setupSteps.forEach((step, i) => { console.log(`${i + 1}. ${step}`); }); } ``` --- ## Benefits ### 1. **Intelligent Automation** - AI-generated commit messages follow best practices - PR descriptions are comprehensive and well-structured - Setup configurations are optimized for your project type ### 2. **Reduced Manual Work** - No more writing PR descriptions manually - No more crafting commit messages - Automated validation and health checks ### 3. **Consistency** - All commit messages follow Conventional Commits - PR descriptions have consistent structure - Setup follows best practices automatically ### 4. **Quality Improvement** - Technical-writer ensures clear, professional documentation - System-architect optimizes configuration - DevOps-architect catches configuration issues ### 5. **Time Savings** - Generating PR descriptions: **5-10 minutes → 10 seconds** - Writing commit messages: **2-3 minutes → 5 seconds** - Setup validation: **15-20 minutes → 30 seconds** - Project onboarding: **30-60 minutes → 5 minutes** --- ## Best Practices ### When to Use Sub-Agents **✅ DO Use Sub-Agents For:** - Complex commit messages with many changes - PR descriptions for large features - Setup validation and configuration - Project onboarding and configuration **❌ DON'T Use Sub-Agents For:** - Simple, single-line changes - Trivial commits ("fix typo") - Quick validation checks - Tasks you can do faster manually ### Performance Considerations - Sub-agents add 5-15 seconds of processing time - Use them when quality > speed - Cache results when possible - Batch operations when appropriate ### Error Handling ```typescript try { const result = await mcpClient.call('generate_smart_commit_message', { gitDiff: diff }); // Use AI-generated message } catch (error) { // Fallback to simple message const fallbackMessage = generateSimpleCommitMessage(diff); return fallbackMessage; } ``` --- ## Future Enhancements ### Planned Sub-Agent Integrations 1. **quality-engineer**: Automated test generation for tasks 2. **security-engineer**: Security review before PR creation 3. **performance-engineer**: Performance impact analysis 4. **pm-agent**: Post-task knowledge capture and documentation 5. **root-cause-analyst**: Intelligent bug investigation ### Roadmap - **Q1 2025**: PR review automation with quality-engineer - **Q2 2025**: Security scanning with security-engineer - **Q3 2025**: Performance benchmarking with performance-engineer - **Q4 2025**: Full PM automation with pm-agent --- ## Troubleshooting ### Sub-Agent Not Launching **Problem**: Claude Code doesn't launch the sub-agent **Solutions**: 1. Check Claude Code version (requires latest) 2. Verify Task tool is available 3. Check MCP server logs for errors 4. Restart Claude Desktop ### Sub-Agent Returns Unexpected Results **Problem**: Sub-agent output doesn't match expectations **Solutions**: 1. Check input data quality (git diffs, task data) 2. Review sub-agent prompt in `subagent-helpers.ts` 3. Add more context to the prompt 4. Use different sub-agent type if appropriate ### Performance Issues **Problem**: Sub-agent calls are too slow **Solutions**: 1. Use sub-agents only for complex tasks 2. Cache results when possible 3. Consider batching operations 4. Use simpler tools for trivial tasks --- ## Examples ### Complete Workflow Example ```typescript // 1. Start work on task await mcp.call('start_work_on_task', { taskId: 'task-123' }); // 2. ... do implementation work ... // 3. Complete work with smart commit message const gitDiff = await getGitDiff(); const commitMsg = await mcp.call('generate_smart_commit_message', { gitDiff, taskContext: { taskId: 'task-123' } }); await mcp.call('complete_task_work', { taskId: 'task-123', summary: '実装完了' }); // 4. Create PR with smart description const branchTasks = await mcp.call('list_branch_tasks'); const prDescription = await mcp.call('generate_smart_pr_description', { branchTasks: branchTasks.tasks, gitDiff: await getGitDiffSummary() }); await mcp.call('create_pull_request', { title: 'Feature: ユーザー認証機能', description: prDescription }); // 5. Validate everything worked await mcp.call('validate_setup'); ``` --- ## Conclusion Sub-agent integration makes EurekaClaude significantly more intelligent and automated. By leveraging Claude Code's specialist agents, you get: - **Professional documentation** automatically - **Optimized configurations** for your project - **Comprehensive validation** of your setup - **Time savings** of 30-60% on routine tasks Start using sub-agents today to supercharge your development workflow! --- ## Related Documentation - [MCP Server Setup](./README.md) - [CLI Tool Usage](./cli/README.md) - [Work Session Guide](./docs/work-sessions.md) - [Git Integration](./docs/git-tracking.md)