Explorer Agent

​

Overview

• Starting work on new or unfamiliar repository
• Mapping out a plan for complex refactor
• Researching feasibility of third-party integration
• Deep-dive architectural audits
• Initial codebase survey needed

​

Core Philosophy

“Understand before acting. Map before modifying.”

​

Key Capabilities

​

Skills Used

• Clean Code - Code quality standards
• Architecture - System design principles
• Plan Writing - Structured documentation
• Brainstorming - Creative problem-solving
• Systematic Debugging - Investigation techniques

​

Expertise

1. Autonomous Discovery: Automatically maps the entire project structure
2. Architectural Reconnaissance: Deep-dives into code to identify patterns
3. Dependency Intelligence: Analyzes what is used and how it’s coupled
4. Risk Analysis: Identifies potential conflicts before they happen
5. Research & Feasibility: Investigates external APIs, libraries, new features
6. Knowledge Synthesis: Acts as primary information source for other agents

​

Advanced Exploration Modes

​

🔍 Audit Mode

• New team member onboarding
• Pre-refactor assessment
• Technical debt evaluation

​

🗺️ Mapping Mode

• Complex refactoring planning
• Understanding system architecture
• Identifying tightly coupled areas

​

🧪 Feasibility Mode

• Evaluating new feature requests
• Third-party integration assessment
• Technology migration planning

​

Example Use Cases

​

Use Case 1: Initial Codebase Survey

Orchestrator: "Survey this codebase before planning"

[Explorer Agent - Autonomous Discovery]

## Phase 1: Project Structure Analysis

```bash
# Scan directory structure
find . -type f -name "*.ts" -o -name "*.tsx" | head -20

.
├── src/
│   ├── app/          # Next.js App Router
│   ├── components/   # React components
│   ├── lib/          # Utilities
│   └── types/        # TypeScript types
├── prisma/        # Database schema
├── public/        # Static assets
└── tests/         # Test files

​

Phase 2: Tech Stack Identification

• Next.js 14 (App Router)
• React 18
• Tailwind CSS
• TypeScript

• Next.js API Routes
• Prisma ORM
• PostgreSQL

• Vitest
• Playwright

• Vercel (detected from vercel.json)

​

Phase 3: Entry Points & Critical Paths

1. src/app/page.tsx - Homepage
2. src/app/api/ - API routes
3. prisma/schema.prisma - Database schema

• Authentication: Custom JWT implementation in src/lib/auth.ts
• Database: Prisma client in src/lib/db.ts

​

Phase 4: Architectural Patterns

• Server Components: Default rendering strategy
• API Routes: RESTful design
• Data Fetching: Direct Prisma queries in Server Components
• State Management: No global state (Server Components + URL state)

​

Phase 5: Code Health Metrics

• Total Files: 87
• TypeScript Coverage: 100%
• Test Coverage: 45% (needs improvement)
• Linting: ESLint configured
• Formatting: Prettier configured

​

Phase 6: Potential Issues

1. No error boundaries (MEDIUM)
   • Impact: Uncaught errors crash entire app
   • Recommendation: Add error boundaries
2. Missing rate limiting (HIGH)
   • Impact: API vulnerable to abuse
   • Files: All /api/ routes
   • Recommendation: Add rate limiting middleware
3. No input validation (CRITICAL)
   • Impact: Potential injection attacks
   • Files: src/app/api/users/route.ts
   • Recommendation: Add Zod validation
4. Large components (MEDIUM)
   • Files: src/components/Dashboard.tsx (450 lines)
   • Recommendation: Split into smaller components

​

Phase 7: Recommendations

1. Use security-auditor for API security review
2. Use test-engineer to improve coverage (45% → 80%)
3. Use frontend-specialist to refactor large components
4. Use backend-specialist to add input validation

​

Summary

### Use Case 2: Feasibility Research

​

Research: Stripe Integration Feasibility

​

1. Current Payment Flow Analysis

• No payment system currently
• Order model exists in prisma/schema.prisma
• Checkout flow in src/app/checkout/page.tsx

​

2. Stripe Integration Requirements

1. Backend: API routes for creating payment intents
2. Frontend: Stripe Elements for card input
3. Database: Store payment status, Stripe customer IDs
4. Webhooks: Handle payment events

​

3. Compatibility Check

• Next.js API routes: Perfect for Stripe webhooks
• TypeScript: Official Stripe types available
• React: Stripe React SDK available
• PostgreSQL: Can store payment metadata

• Need HTTPS for webhooks (production only)
• Need webhook secret management
• Need idempotency handling

​

4. Effort Estimation

1. Install Stripe SDK (npm install stripe @stripe/stripe-js)
2. Create API routes:
   • POST /api/create-payment-intent
   • POST /api/webhooks/stripe
3. Update database schema:
   • Add stripeCustomerId to User
   • Add paymentStatus to Order
4. Implement frontend:
   • Stripe Elements component
   • Payment form
5. Test with Stripe test mode

​

5. Risks & Mitigations

​

6. Recommendation

1. backend-specialist: Stripe API routes and webhooks
2. database-architect: Schema changes
3. frontend-specialist: Checkout UI with Stripe Elements
4. test-engineer: Payment flow E2E tests
5. security-auditor: Security review of payment flow

### Use Case 3: Dependency Analysis

​

Bundle Analysis

​

1. Dependency Tree

npm list --depth=0

​

2. Large Dependencies Identified

​

3. Coupling Analysis

• moment imported in 15 components
  • Risk: Hard to replace
  • Recommendation: Use date-fns (tree-shakeable)

• chart.js only in Dashboard
  • Risk: Low
  • Recommendation: Code split

​

4. Optimization Recommendations

1. Replace moment with date-fns
   • Before: 300KB
   • After: 15KB (only imported functions)
   • Files affected: 15

• Before: import _ from 'lodash'
• After: import debounce from 'lodash/debounce'

• Lazy load dashboard module

​

5. Migration Plan

1. Create task: Replace moment with date-fns
2. Create task: Optimize lodash imports
3. Create task: Implement code splitting

## Discovery Flow

1. **Initial Survey**: List directories, find entry points
2. **Dependency Tree**: Trace imports and exports for data flow
3. **Pattern Identification**: Search for architectural signatures
4. **Resource Mapping**: Identify assets, configs, environment variables
5. **Risk Assessment**: Flag potential issues
6. **Knowledge Synthesis**: Compile report for other agents

## Review Checklist

- [ ] Architectural pattern clearly identified?
- [ ] All critical dependencies mapped?
- [ ] Hidden side effects in core logic identified?
- [ ] Tech stack consistent with modern best practices?
- [ ] Unused or dead code sections flagged?

## Best Practices

<CardGroup cols={2}>
  <Card title="Survey First" icon="map">
    Always map before modifying - understand the landscape
  </Card>
  <Card title="Document Findings" icon="file-lines">
    Create clear reports for other agents to use
  </Card>
  <Card title="Identify Risks" icon="triangle-exclamation">
    Proactively flag potential issues before they become problems
  </Card>
  <Card title="Provide Context" icon="lightbulb">
    Explain why things exist, not just what they are
  </Card>
</CardGroup>

## Automatic Selection Triggers

Explorer Agent is automatically selected when:
- Orchestrator needs codebase mapping
- User asks to "analyze", "explore", "survey" codebase
- User requests "architecture review", "dependency analysis"
- Feasibility research needed

## Related Agents

<CardGroup cols={2}>
  <Card title="Orchestrator" icon="sitemap" href="/agents/orchestrator">
    Uses Explorer findings to coordinate other agents
  </Card>
  <Card title="Project Planner" icon="list-check" href="/agents/project-planner">
    Uses Explorer findings to create execution plans
  </Card>
</CardGroup>