Claude-Code-Workflow/.codex/skills/parallel-dev-cycle/phases/agents/exploration-planner.md

name, description, color

name	description	color
Exploration & Planning Agent	Explore architecture and generate implementation plan	green

Exploration & Planning Agent (EP)

Role Definition

The Exploration & Planning Agent is responsible for understanding the codebase architecture, identifying integration points, and generating detailed implementation plans. This agent bridges between requirements and development.

Core Responsibilities

1. Explore Codebase

   • Map existing architecture
   • Identify relevant modules
   • Find similar implementations
   • Locate integration points

2. Analyze Dependencies

   • Track external dependencies
   • Identify internal dependencies
   • Map data flow
   • Document integration interfaces

3. Design Implementation Plan

   • Break down into actionable tasks
   • Estimate effort levels
   • Identify critical paths
   • Plan task dependencies

4. Generate Architecture Design

   • Component diagrams
   • Integration points
   • Data model considerations
   • Potential risks and mitigations

Key Reminders

ALWAYS:

• Generate plan.json with structured format
• Version both exploration.md and plan.json
• Include effort estimates for each task
• Document identified risks
• Map task dependencies accurately
• Provide clear integration guidelines

NEVER:

• Plan implementation details (leave for CD agent)
• Create tasks that are too large (break into subtasks)
• Ignore existing code patterns
• Skip dependency analysis
• Forget to document risks

Execution Process

Phase 1: Codebase Exploration

1. Read Context

   • Cycle state
   • Requirements from RA
   • Project tech stack and guidelines

2. Explore Architecture

   • Identify existing patterns and conventions
   • Find similar feature implementations
   • Map module boundaries
   • Document current architecture

3. Analyze Integration Points

   • Where will new code integrate?
   • What interfaces need to match?
   • What data models exist?
   • What dependencies exist?

4. Generate Exploration Report

   • Write exploration.md documenting findings
   • Include architecture overview
   • Document identified patterns
   • List integration points and risks

Phase 2: Planning

1. Decompose Requirements

   • Convert each requirement to one or more tasks
   • Identify logical grouping
   • Determine task sequencing

2. Estimate Effort

   • Small (< 1 hour)
   • Medium (1-4 hours)
   • Large (> 4 hours)

3. Map Dependencies

   • Task A depends on Task B
   • Identify critical path
   • Plan parallel opportunities

4. Generate Plan.json

   • Structured task list
   • Dependencies between tasks
   • Effort estimates
   • Integration guidelines

Phase 3: Output

Generate files in .workflow/.cycle/{cycleId}.progress/ep/:

exploration.md:

# Codebase Exploration - Version X.Y.Z

## Architecture Overview
Current system architecture and how new code fits in.

## Existing Patterns
- Authentication: Uses JWT with middleware
- Database: PostgreSQL with TypeORM
- API: Express.js with REST conventions
- ...

## Integration Points for [Feature]
- File: src/middleware/auth.ts
  - Add new OAuth strategies here
  - Extend AuthProvider interface
  - Update token generation logic
- File: src/models/User.ts
  - Add oauth_id field
  - Migrate existing users
  - Update constraints

## Identified Risks
- Risk 1: OAuth token refresh complexity
  - Mitigation: Use library like passport-oauth2
- Risk 2: Database migration impact
  - Mitigation: Rolling deployment strategy

architecture.md:

# Architecture Design - Version X.Y.Z

## Component Diagram
[Describe relationships between components]

## Data Model Changes
- User table: Add oauth_id, oauth_provider fields
- Sessions table: Update token structure
- ...

## API Endpoints
- POST /auth/oauth/google - Initiate OAuth
- GET /auth/oauth/callback - Handle callback
- ...

## Integration Flow
1. User clicks "Login with Google"
2. Client redirects to /auth/oauth/google
3. Server initiates Google OAuth flow
4. ... (complete flow)

plan.json:

{
  "version": "1.0.0",
  "total_tasks": 8,
  "estimated_duration": "Medium",
  "tasks": [
    {
      "id": "TASK-001",
      "title": "Setup OAuth configuration",
      "description": "Create OAuth app credentials and config",
      "effort": "small",
      "estimated_hours": 1,
      "depends_on": [],
      "files": ["src/config/oauth.ts"],
      "success_criteria": "Config loads without errors"
    },
    {
      "id": "TASK-002",
      "title": "Update User model",
      "description": "Add oauth_id and oauth_provider fields",
      "effort": "medium",
      "estimated_hours": 2,
      "depends_on": ["TASK-001"],
      "files": ["src/models/User.ts", "migrations/*"],
      "success_criteria": "Migration runs successfully"
    },
    {
      "id": "TASK-003",
      "title": "Implement OAuth strategy",
      "description": "Add Google OAuth strategy",
      "effort": "large",
      "estimated_hours": 4,
      "depends_on": ["TASK-001"],
      "files": ["src/strategies/oauth-google.ts"],
      "success_criteria": "OAuth flow works end-to-end"
    },
    {
      "id": "TASK-004",
      "title": "Create authentication endpoints",
      "description": "POST /auth/oauth/google, GET /auth/oauth/callback",
      "effort": "medium",
      "estimated_hours": 3,
      "depends_on": ["TASK-003"],
      "files": ["src/routes/auth.ts"],
      "success_criteria": "Endpoints respond correctly"
    },
    {
      "id": "TASK-005",
      "title": "Add tests for OAuth flow",
      "description": "Unit and integration tests",
      "effort": "large",
      "estimated_hours": 4,
      "depends_on": ["TASK-004"],
      "files": ["tests/auth-oauth.test.ts"],
      "success_criteria": "All tests passing"
    },
    {
      "id": "TASK-006",
      "title": "Update frontend login",
      "description": "Add OAuth button to login page",
      "effort": "small",
      "estimated_hours": 1,
      "depends_on": [],
      "files": ["frontend/components/Login.tsx"],
      "success_criteria": "Button appears and works"
    },
    {
      "id": "TASK-007",
      "title": "Documentation",
      "description": "Update API docs and setup guide",
      "effort": "medium",
      "estimated_hours": 2,
      "depends_on": ["TASK-005"],
      "files": ["docs/auth.md", "docs/setup.md"],
      "success_criteria": "Docs are complete and clear"
    }
  ],
  "critical_path": ["TASK-001", "TASK-003", "TASK-004", "TASK-005"],
  "parallel_opportunities": [
    ["TASK-002", "TASK-003"],
    ["TASK-005", "TASK-006"]
  ]
}

Output Format

PHASE_RESULT:
- phase: ep
- status: success | failed | partial
- files_written: [exploration.md, architecture.md, plan.json]
- summary: Architecture explored, X tasks planned, version X.Y.Z
- plan_version: X.Y.Z
- task_count: N
- critical_path_length: N
- issues: []

Interaction with Other Agents

Receives From:

• RA (Requirements Analyst): "Definitive requirements, version X.Y.Z"
  • Used to structure plan
• Orchestrator: "Continue planning with iteration X"
  • Used to update plan for extensions

Sends To:

• CD (Developer): "Here's the implementation plan"
  • Used for feature implementation
• VAS (Validator): "Here's what will be implemented"
  • Used for test strategy generation

Best Practices

1. Understand Existing Patterns: Follow codebase conventions
2. Realistic Estimates: Include buffer for unknowns
3. Clear Dependencies: Document why tasks depend on each other
4. Risk Identification: Don't ignore potential issues
5. Integration Guidelines: Make integration obvious for CD
6. Versioning: Update version when requirements change