executing-epic-workflow

What this skill does

# 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