Executing EPIC Workflow

1. Context

• Main Objective: Execute feature development using the EPIC methodology (Explore, Research, Plan, Validate, Implement, Review, Iterate)
• Secondary Objective: Ensure proper delegation to specialized subagents for each phase
• User Input: Feature description, requirements, or task specification
• Workflow: Explore → Research → Plan → Validate Plan → Implement → Review → Iterate (main agent only implements)

CRITICAL: Session Directory Initialization

BEFORE starting any EPIC phase, the main agent MUST:

1. Create session directory: .claude/sessions/[NN]-[session-description]/
   • [NN]: Two-digit sequential number (01, 02, 03, etc.)
   • [session-description]: Short hyphenated description (e.g., user-auth-feature, payment-integration)
2. Store the session directory path for use throughout the workflow
3. ALWAYS instruct ALL subagents to save their reports to this session directory

Example:

• Session directory: .claude/sessions/01-user-auth-feature/
• When delegating to any subagent, ALWAYS include: "Save your report to .claude/sessions/01-user-auth-feature/[required-filename].md"

2. Workflow

Phase 1: Explore

Objective: Gather comprehensive context about the codebase and existing implementations

• T001: Initialize session directory [P0]

  • Determine next sequential number by checking existing .claude/sessions/ directories
  • Create new session directory: .claude/sessions/[NN]-[session-description]/
  • Example: .claude/sessions/01-user-auth-feature/
  • Store this path as SESSION_DIR for use in all subsequent phases

• T002: Delegate exploration to codebase-explorer agent [P0]

  • CRITICAL: Include explicit save instruction in delegation prompt:

    "Please analyze the current project status, identify relevant files and components,
    assess recent changes and technical dependencies, and document the current state
    of related features.
    
    IMPORTANT: Save your complete exploration report to:
    [SESSION_DIR]/codebase-status.md
    
    The report must be saved to this exact location for workflow validation."
    

  • Request analysis of current project status
  • Identify relevant files and components
  • Assess recent changes and technical dependencies
  • Document current state of related features
  • Agent MUST save report to: [SESSION_DIR]/codebase-status.md

• T003: Review exploration findings [P0]

  • Read the generated report: [SESSION_DIR]/codebase-status.md
  • Synthesize discovered information
  • Identify gaps or areas needing clarification
  • Prepare context for research phase

• T004: Validate phase completion [P0]

  • Run: python .claude/skills/epic/scripts/validate-phase.py explore [SESSION_DIR]
  • ITERATIVE COMPLIANCE FLOW:
    • If validation PASSES: Proceed to Phase 2 (Research)
    • If validation FAILS:
      1. Reinvoke codebase-explorer agent with EXPLICIT instruction: "Save your report to [SESSION_DIR]/codebase-status.md"
      2. Re-run validation script
      3. Repeat steps 1-2 until validation passes
    • CRITICAL: Do NOT proceed to next phase until validation passes

Phase 2: Research

Objective: Conduct comprehensive research on complex topics and validate approaches

• T005: Delegate research tasks to research-specialist agent [P0]

  • CRITICAL: Include explicit save instruction in delegation prompt:

    "Please conduct comprehensive research on [specific topics], validate approaches
    across multiple sources, perform deep web investigations if needed, and synthesize
    findings into actionable insights.
    
    IMPORTANT: Save your complete research report to:
    [SESSION_DIR]/research-report.md
    
    The report must be saved to this exact location for workflow validation."
    

  • Conduct research on complex topics
  • Validate approaches across multiple sources
  • Perform deep web investigations if needed
  • Synthesize findings into actionable insights
  • Agent MUST save report to: [SESSION_DIR]/research-report.md

• T006: Review research findings [P0]

  • Read the generated report: [SESSION_DIR]/research-report.md
  • Identify best practices and patterns
  • Document technical recommendations
  • Prepare foundation for planning phase

• T007: Validate phase completion [P0]

  • Run: python .claude/skills/epic/scripts/validate-phase.py research [SESSION_DIR]
  • ITERATIVE COMPLIANCE FLOW:
    • If validation PASSES: Proceed to Phase 3 (Plan)
    • If validation FAILS:
      1. Reinvoke research-specialist agent with EXPLICIT instruction: "Save your report to [SESSION_DIR]/research-report.md"
      2. Re-run validation script
      3. Repeat steps 1-2 until validation passes
    • CRITICAL: Do NOT proceed to next phase until validation passes

Phase 3: Plan

Objective: Develop comprehensive implementation strategy

• T008: Delegate strategic planning to strategic-planner agent [P0]

  • CRITICAL: Include explicit save instruction in delegation prompt:

    "Please analyze the problem comprehensively using the exploration and research
    findings from [SESSION_DIR]/codebase-status.md and [SESSION_DIR]/research-report.md.
    Devise optimal solution approaches, identify multiple implementation paths, and
    evaluate trade-offs and risks.
    
    IMPORTANT: Save your complete implementation plan to:
    [SESSION_DIR]/implementation-plan.md
    
    The plan must be saved to this exact location for workflow validation."
    

  • Provide paths to exploration and research reports for context
  • Analyze problem comprehensively using exploration and research findings
  • Devise optimal solution approaches
  • Identify multiple implementation paths
  • Evaluate trade-offs and risks
  • Agent MUST save report to: [SESSION_DIR]/implementation-plan.md

• T009: Review and consolidate plan [P0]

  • Read the generated plan: [SESSION_DIR]/implementation-plan.md
  • Integrate insights from exploration and research
  • Verify comprehensive implementation roadmap exists
  • Confirm success criteria and validation steps are defined

• T010: Validate phase completion [P0]

  • Run: python .claude/skills/epic/scripts/validate-phase.py plan [SESSION_DIR]
  • ITERATIVE COMPLIANCE FLOW:
    • If validation PASSES: Proceed to Phase 4 (Validate Plan)
    • If validation FAILS:
      1. Reinvoke strategic-planner agent with EXPLICIT instruction: "Save your plan to [SESSION_DIR]/implementation-plan.md"
      2. Re-run validation script
      3. Repeat steps 1-2 until validation passes
    • CRITICAL: Do NOT proceed to next phase until validation passes

Phase 4: Validate Plan

Objective: Critical review and validation of proposed approach

• T011: Delegate plan validation to consulting-expert agent [P0]

  • CRITICAL: Include explicit save instruction in delegation prompt:

    "Please review the implementation plan at [SESSION_DIR]/implementation-plan.md
    objectively. Identify potential risks and over-complications, suggest pragmatic
    alternatives, and validate alignment with best practices.
    
    IMPORTANT: Save your complete validation feedback to:
    [SESSION_DIR]/validation-feedback.md
    
    The feedback must be saved to this exact location for workflow validation."
    

  • Provide path to implementation plan for review
  • Review proposed approaches objectively
  • Identify potential risks and over-complications
  • Suggest pragmatic alternatives
  • Validate alignment with best practices
  • Agent MUST save report to: [SESSION_DIR]/validation-feedback.md

• T012: Refine plan based on validation feedback [P0]

  • Read the validation feedback: [SESSION_DIR]/validation-feedback.md
  • Address identified concerns
  • Simplify over-complicated approaches
  • Update [SESSION_DIR]/implementation-plan.md with refinements if needed
  • Finalize implementation strategy

• T013: Validate p