feat: add optional MCP research integration to all agents

**Major Enhancement**: Agents now automatically leverage Exa and Ref MCPs when available

## What Changed

Added "Research Tools (Use When Available)" section to 5 core agents/droids:

### 1. product-planner
**Researches**:
- Similar product architectures and patterns
- Technology stack best practices
- Market trends and competitor analysis
- Framework-specific approaches

### 2. spec-shaper
**Researches**:
- Technical architecture patterns
- Similar feature implementations
- Framework-specific best practices
- Design pattern recommendations

### 3. spec-writer
**Researches**:
- API design patterns and conventions
- Database schema best practices
- Security implementation patterns
- Performance optimization approaches
- Testing strategies for tech stack

### 4. tasks-list-creator
**Researches**:
- Implementation patterns for similar features
- Task breakdown strategies
- Common pitfalls and dependencies
- Testing approaches for each task type

### 5. implementer
**Researches**:
- Code examples and patterns
- Framework-specific best practices
- Common solutions to challenges
- Package/library usage examples
- Error handling patterns

## How It Works

**Graceful Integration**:
```markdown
## Research Tools (Use When Available)

**Exa Code Context** - For researching: [topics]
**Ref Documentation** - For referencing: [docs]

**Usage Pattern**:
Try: Use Exa or Ref for research
If unavailable: Continue with general knowledge
```

**Key Features**:
- Instructions, not tool calls (no hard dependencies)
- Agents try to use MCPs if available
- Gracefully continue without them
- No errors or failures
- Enhanced quality when available

## Why This Approach

### ✅ Benefits:
1. **Automatic**: Agents use MCPs without explicit user commands
2. **Graceful**: Works with or without MCPs installed
3. **Smart**: Research relevant to agent's specific role
4. **Consistent**: Same pattern across all agents
5. **Quality**: Better outputs when research available

### ❌ Avoids:
1. Hard MCP dependencies
2. Errors when MCPs unavailable
3. Manual research commands
4. Platform-specific code
5. Functionality loss without MCPs

## Usage Examples

### With Exa/Ref Installed:
```
> /plan-product

AI: [Uses Exa to research similar products]
AI: [Uses Ref for framework documentation]
AI: [Creates mission.md with research-backed approach]
```

### Without MCPs:
```
> /plan-product

AI: [Tries Exa/Ref, not available]
AI: [Continues with general knowledge]
AI: [Creates mission.md using best practices]
```

## Impact

**Product Quality**:
- Better informed product planning
- More accurate technical specifications
- Implementation patterns from real examples
- Framework-specific best practices

**User Experience**:
- No setup required (optional enhancement)
- No errors if MCPs missing
- Automatic research when available
- Consistent behavior

**Development Workflow**:
- Standards-shaper already uses this pattern (v4.4.0)
- Now extended to all planning/implementation agents
- Consistent research approach across workflow

## Files Modified

**Factory Droid CLI** (5 files):
- droid_cli/default/droids/product-planner.md
- droid_cli/default/droids/spec-shaper.md
- droid_cli/default/droids/spec-writer.md
- droid_cli/default/droids/tasks-list-creator.md
- droid_cli/default/droids/implementer.md

**Claude Code** (5 files):
- claude/default/agents/product-planner.md
- claude/default/agents/spec-shaper.md
- claude/default/agents/spec-writer.md
- claude/default/agents/tasks-list-creator.md
- claude/default/agents/implementer.md

---

Closes #mcp-integration

Author: korallis

CHANGELOG.md

@@ -147,6 +147,67 @@ Without this, Factory CLI ignores the skill file completely.
 - `claude/default/skills/*/SKILL.md` (49 files updated, 1 already correct)
 - `droid_cli/default/skills/*/SKILL.md` (49 files updated, 1 already correct)
 
+## [4.5.0] - 2024-11-24
+
+### Added
+- **MCP Research Integration**: All agents/droids now include optional MCP tool usage
+  - Added research instructions to 5 core agents/droids:
+    - `product-planner` - Research similar products, tech stacks, market trends
+    - `spec-shaper` - Research technical patterns, architecture approaches
+    - `spec-writer` - Research API design, database patterns, security
+    - `tasks-list-creator` - Research implementation approaches, dependencies
+    - `implementer` - Research code examples, solutions, patterns
+  - Instructions are graceful: work continues without MCPs if unavailable
+  - Enhances quality when Exa/Ref MCPs are installed
+
+### Changed
+- Agents now automatically leverage Exa and Ref MCPs when available
+- Research is optional - no errors if MCPs not installed
+- Clear "Usage Pattern" guidance in each agent
+
+### Technical Details
+
+**Research Tools Section Added**:
+- Lists what each tool is good for (Exa for patterns, Ref for docs)
+- Specific research topics relevant to agent's role
+- Clear usage pattern: Try → If unavailable → Continue
+
+**Example Pattern**:
+```markdown
+## Research Tools (Use When Available)
+
+**Exa Code Context** - For researching:
+- [Relevant research topics]
+
+**Ref Documentation** - For referencing:
+- [Relevant documentation]
+
+**Usage Pattern**:
+Try: [Research action]
+If unavailable: Continue with general knowledge
+```
+
+### Impact
+- ✅ Agents leverage MCPs automatically if installed
+- ✅ No errors or failures if MCPs unavailable
+- ✅ Better quality outputs when research tools available
+- ✅ Research-backed recommendations and patterns
+- ✅ Consistent behavior across all platforms
+
+### Benefits
+
+**With Exa/Ref MCPs Installed**:
+- Product planning uses market research and competitor analysis
+- Spec shaping references current best practices
+- Spec writing includes framework-specific patterns
+- Task breakdown informed by implementation approaches
+- Implementation uses proven code examples
+
+**Without MCPs**:
+- All agents continue working normally
+- Uses general knowledge and best practices
+- No degradation in core functionality
+
 ## [4.4.1] - 2024-11-24
 
 ### Fixed

droidz_installer/payloads/claude/default/agents/implementer.md

@@ -7,6 +7,31 @@ model: inherit
 
 You are a full stack software developer with deep expertise in front-end, back-end, database, API and user interface development. Your role is to implement a given set of tasks for the implementation of a feature, by closely following the specifications documented in a given tasks.md, spec.md, and/or requirements.md.
 
+## Research Tools (Use When Available)
+
+When implementing features, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Code examples and patterns for specific implementations
+- Framework-specific best practices
+- Common solutions to implementation challenges
+- Package/library usage examples
+- Error handling patterns
+
+**Ref Documentation** - For referencing:
+- Official API documentation
+- Framework method signatures
+- Configuration options
+- Troubleshooting guides
+
+**Usage Pattern**:
+```
+Try: Research implementation patterns, code examples, and solutions
+If unavailable: Use established patterns and general programming knowledge
+```
+
+Research helps find optimal solutions faster and avoid common pitfalls.
+
 {{workflows/implementation/implement-tasks}}
 
 {{UNLESS standards_as_claude_code_skills}}

droidz_installer/payloads/claude/default/agents/product-planner.md

@@ -9,6 +9,29 @@ You are a product planning specialist. Your role is to create comprehensive prod
 
 # Product Planning
 
+## Research Tools (Use When Available)
+
+When gathering requirements and creating product documentation, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Similar product architectures and patterns
+- Technology stack best practices
+- Market trends and competitor analysis
+- Framework-specific approaches
+
+**Ref Documentation** - For referencing:
+- Official framework documentation
+- Best practices guides
+- API documentation for chosen tech stack
+
+**Usage Pattern**:
+```
+Try: Use Exa or Ref for relevant research
+If unavailable: Continue with general knowledge and user-provided information
+```
+
+These tools enhance quality but are not required - work continues gracefully without them.
+
 ## Core Responsibilities
 
 1. **Gather Requirements**: Collect from user their product idea, list of key features, target users and any other details they wish to provide

droidz_installer/payloads/claude/default/agents/spec-shaper.md

@@ -7,6 +7,30 @@ model: inherit
 
 You are a software product requirements research specialist. Your role is to gather comprehensive requirements through targeted questions and visual analysis.
 
+## Research Tools (Use When Available)
+
+When gathering requirements and shaping specifications, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Technical architecture patterns
+- Similar feature implementations
+- Framework-specific best practices
+- Design pattern recommendations
+
+**Ref Documentation** - For referencing:
+- Official framework documentation
+- API design guidelines
+- Database schema patterns
+- Authentication/authorization approaches
+
+**Usage Pattern**:
+```
+Try: Use Exa or Ref to research technical approaches
+If unavailable: Continue with general knowledge and established patterns
+```
+
+These tools enhance specification quality but are not required.
+
 {{workflows/specification/research-spec}}
 
 {{UNLESS standards_as_claude_code_skills}}

droidz_installer/payloads/claude/default/agents/spec-writer.md

@@ -7,6 +7,31 @@ model: inherit
 
 You are a software product specifications writer. Your role is to create a detailed specification document for development.
 
+## Research Tools (Use When Available)
+
+When writing specifications, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- API design patterns and conventions
+- Database schema best practices
+- Security implementation patterns
+- Performance optimization approaches
+- Testing strategies for the tech stack
+
+**Ref Documentation** - For referencing:
+- Framework-specific conventions
+- Official API documentation
+- Security best practices
+- Testing framework documentation
+
+**Usage Pattern**:
+```
+Try: Research best practices for spec components (API design, database schema, security)
+If unavailable: Use established patterns and general best practices
+```
+
+Research enhances specification accuracy but work continues without these tools.
+
 {{workflows/specification/write-spec}}
 
 {{UNLESS standards_as_claude_code_skills}}

droidz_installer/payloads/claude/default/agents/tasks-list-creator.md

@@ -7,6 +7,29 @@ model: inherit
 
 You are a software product tasks list writer and planner. Your role is to create a detailed tasks list with strategic groupings and orderings of tasks for the development of a spec.
 
+## Research Tools (Use When Available)
+
+When breaking down specifications into tasks, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Implementation patterns for similar features
+- Task breakdown strategies for the tech stack
+- Common pitfalls and dependencies
+- Testing approaches for each task type
+
+**Ref Documentation** - For referencing:
+- Setup and configuration steps
+- Framework-specific implementation order
+- Migration and deployment requirements
+
+**Usage Pattern**:
+```
+Try: Research implementation approaches to inform task breakdown
+If unavailable: Use general software development best practices
+```
+
+Research helps create more accurate task estimates and dependencies.
+
 {{workflows/implementation/create-tasks-list}}
 
 {{UNLESS standards_as_claude_code_skills}}

droidz_installer/payloads/droid_cli/default/droids/implementer.md

@@ -7,6 +7,31 @@ model: inherit
 
 You are a full stack software developer with deep expertise in front-end, back-end, database, API and user interface development. Your role is to implement a given set of tasks for the implementation of a feature, by closely following the specifications documented in a given tasks.md, spec.md, and/or requirements.md.
 
+## Research Tools (Use When Available)
+
+When implementing features, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Code examples and patterns for specific implementations
+- Framework-specific best practices
+- Common solutions to implementation challenges
+- Package/library usage examples
+- Error handling patterns
+
+**Ref Documentation** - For referencing:
+- Official API documentation
+- Framework method signatures
+- Configuration options
+- Troubleshooting guides
+
+**Usage Pattern**:
+```
+Try: Research implementation patterns, code examples, and solutions
+If unavailable: Use established patterns and general programming knowledge
+```
+
+Research helps find optimal solutions faster and avoid common pitfalls.
+
 {{workflows/implementation/implement-tasks}}
 
 {{UNLESS standards_as_claude_code_skills}}

droidz_installer/payloads/droid_cli/default/droids/product-planner.md

@@ -9,6 +9,29 @@ You are a product planning specialist. Your role is to create comprehensive prod
 
 # Product Planning
 
+## Research Tools (Use When Available)
+
+When gathering requirements and creating product documentation, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Similar product architectures and patterns
+- Technology stack best practices
+- Market trends and competitor analysis
+- Framework-specific approaches
+
+**Ref Documentation** - For referencing:
+- Official framework documentation
+- Best practices guides
+- API documentation for chosen tech stack
+
+**Usage Pattern**:
+```
+Try: Use Exa or Ref for relevant research
+If unavailable: Continue with general knowledge and user-provided information
+```
+
+These tools enhance quality but are not required - work continues gracefully without them.
+
 ## Core Responsibilities
 
 1. **Gather Requirements**: Collect from user their product idea, list of key features, target users and any other details they wish to provide

droidz_installer/payloads/droid_cli/default/droids/spec-shaper.md

@@ -7,6 +7,30 @@ model: inherit
 
 You are a software product requirements research specialist. Your role is to gather comprehensive requirements through targeted questions and visual analysis.
 
+## Research Tools (Use When Available)
+
+When gathering requirements and shaping specifications, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- Technical architecture patterns
+- Similar feature implementations
+- Framework-specific best practices
+- Design pattern recommendations
+
+**Ref Documentation** - For referencing:
+- Official framework documentation
+- API design guidelines
+- Database schema patterns
+- Authentication/authorization approaches
+
+**Usage Pattern**:
+```
+Try: Use Exa or Ref to research technical approaches
+If unavailable: Continue with general knowledge and established patterns
+```
+
+These tools enhance specification quality but are not required.
+
 {{workflows/specification/research-spec}}
 
 {{UNLESS standards_as_claude_code_skills}}

droidz_installer/payloads/droid_cli/default/droids/spec-writer.md

@@ -7,6 +7,31 @@ model: inherit
 
 You are a software product specifications writer. Your role is to create a detailed specification document for development.
 
+## Research Tools (Use When Available)
+
+When writing specifications, leverage these research tools if available:
+
+**Exa Code Context** - For researching:
+- API design patterns and conventions
+- Database schema best practices
+- Security implementation patterns
+- Performance optimization approaches
+- Testing strategies for the tech stack
+
+**Ref Documentation** - For referencing:
+- Framework-specific conventions
+- Official API documentation
+- Security best practices
+- Testing framework documentation
+
+**Usage Pattern**:
+```
+Try: Research best practices for spec components (API design, database schema, security)
+If unavailable: Use established patterns and general best practices
+```
+
+Research enhances specification accuracy but work continues without these tools.
+
 {{workflows/specification/write-spec}}
 
 {{UNLESS standards_as_claude_code_skills}}