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:

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)
Store the session directory path for use throughout the workflow
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 phase completion [P0]
- Run: python .claude/skills/epic/scripts/validate-phase.py validate [SESSION_DIR]
- ITERATIVE COMPLIANCE FLOW:
  - If validation PASSES: Proceed to Phase 5 (Implement)
  - If validation FAILS:
    1. Reinvoke consulting-expert agent with EXPLICIT instruction: "Save your feedback to [SESSION_DIR]/validation-feedback.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 5: Implement

Objective: Execute the implementation directly as the main agent

T014: Set up implementation tracking with TodoWrite tool [P0]
- Read the finalized plan: [SESSION_DIR]/implementation-plan.md
- Break down plan into actionable tasks
- Create todo list with clear status tracking
- Mark tasks as in_progress when working on them
T015: Execute implementation following the plan [P0]
- Write code according to specifications from [SESSION_DIR]/implementation-plan.md
- Follow established patterns from [SESSION_DIR]/codebase-status.md
- Implement one task at a time
- Mark todos as completed immediately after finishing
T016: Handle errors and blockers [P1]
- Keep tasks as in_progress if encountering issues
- Create new tasks for blockers that need resolution
- Never mark incomplete work as completed
T017: Document implementation completion [P0]
- Add inline comments where logic isn't self-evident
- Update relevant documentation files if needed
- Note any deviations from original plan
- CRITICAL: Main agent creates implementation summary:
```
Save a summary of what was implemented, key decisions made, and any
deviations from the plan to:
[SESSION_DIR]/implementation-complete.md

This file is required for workflow validation.
```
T018: Validate phase completion [P0]
- Run: python .claude/skills/epic/scripts/validate-phase.py implement [SESSION_DIR]
- ITERATIVE COMPLIANCE FLOW:
  - If validation PASSES: Proceed to Phase 6 (Review)
  - If validation FAILS (missing implementation-complete.md):
    1. Main agent creates [SESSION_DIR]/implementation-complete.md with summary
    2. Re-run validation script
    3. Repeat until validation passes
  - CRITICAL: Do NOT proceed to next phase until validation passes

Phase 6: Review

Objective: Validate implementation quality through specialized review

T019: Delegate code review to appropriate review agent [P0]

CRITICAL: Include explicit save instruction in delegation prompt:

"Please review the implementation comprehensively. Review the code changes,
check for code quality, performance, and security issues. Reference the
implementation summary at [SESSION_DIR]/implementation-complete.md.

IMPORTANT: Save your complete quality review to:
[SESSION_DIR]/quality-report.md

The report must be saved to this exact location for workflow validation.
Include all findings, recommendations, and severity levels."

For code quality: Use general review processes
For security: Consider security-expert agent
Request comprehensive feedback on implementation
Agent MUST save report to: [SESSION_DIR]/quality-report.md

T020: Delegate testing validation to test-engineer agent if tests exist [P1]
- CRITICAL: Include save instruction in delegation prompt
- Ensure tests pass for critical business logic
- Validate test coverage
- Review test data and mocking patterns
- Results should be appended to: [SESSION_DIR]/quality-report.md
T021: Compile review findings [P0]
- Read the quality report: [SESSION_DIR]/quality-report.md
- Document all feedback from review agents
- Prioritize issues by severity
- Prepare for iteration phase if needed
T022: Validate phase completion [P0]
- Run: python .claude/skills/epic/scripts/validate-phase.py review [SESSION_DIR]
- ITERATIVE COMPLIANCE FLOW:
  - If validation PASSES: Proceed to Phase 7 (Iterate) if issues found, or complete workflow if no issues
  - If validation FAILS:
    1. Reinvoke review agents with EXPLICIT instruction: "Save your report to [SESSION_DIR]/quality-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 7: Iterate

Objective: Address feedback and resolve issues until quality standards are met

T023: Delegate troubleshooting to troubleshooter agent if issues found [P0]
- CRITICAL: Include explicit save instruction in delegation prompt if issues exist:
```
"Please diagnose and resolve the errors/bugs/build failures found in the
quality report at [SESSION_DIR]/quality-report.md.

OPTIONAL: If troubleshooting is performed, save your troubleshooting report to:
[SESSION_DIR]/troubleshooting-report.md

This file is optional but helpful for documentation."
```
- Diagnose errors, bugs, or build failures
- Resolve runtime exceptions
- Fix configuration problems
- Agent MAY save report to: [SESSION_DIR]/troubleshooting-report.md (optional)
T024: Address review feedback (main agent) [P0]
- Read the quality report: [SESSION_DIR]/quality-report.md
- Implement suggested improvements
- Fix identified issues
- Update [SESSION_DIR]/implementation-complete.md with changes made
T025: Repeat review phase if significant changes made [P1]
- If major modifications were implemented, return to Phase 6
- Ensure changes don't introduce regressions
- This creates an iteration loop: Review → Iterate → Review until quality passes

T026: Final verification [P0]

Confirm all success criteria from [SESSION_DIR]/implementation-plan.md are met
Verify no regressions introduced

CRITICAL: Main agent creates final verification summary:

Save a summary confirming all criteria are met, no regressions exist,
and the implementation is complete to:
[SESSION_DIR]/final-verification.md

This file is required for workflow validation.

T027: Validate phase completion [P0]
- Run: python .claude/skills/epic/scripts/validate-phase.py iterate [SESSION_DIR]
- ITERATIVE COMPLIANCE FLOW:
  - If validation PASSES: EPIC workflow complete ✅
  - If validation FAILS:
    1. Main agent creates [SESSION_DIR]/final-verification.md with summary
    2. Re-run validation script
    3. Repeat until validation passes
  - CRITICAL: Do NOT mark workflow complete until validation passes

3. Implementation Strategy

Agent Delegation Pattern

CRITICAL: ALL delegation prompts MUST include explicit save instructions to SESSION_DIR

Phase 1 - Explore:

Use Task tool with subagent_type="codebase-explorer"
MUST include in prompt: "Save your report to [SESSION_DIR]/codebase-status.md"
Provide specific investigation goals
Request comprehensive analysis of current state

Phase 2 - Research:

Use Task tool with subagent_type="research-specialist"
MUST include in prompt: "Save your report to [SESSION_DIR]/research-report.md"
Conduct research on complex topics
Validate approaches across multiple sources

Phase 3 - Plan:

Use Task tool with subagent_type="strategic-planner"
MUST include in prompt: "Save your plan to [SESSION_DIR]/implementation-plan.md"
Provide paths to previous reports for context
Analyze problem using exploration and research findings
Devise optimal solution approaches

Phase 4 - Validate Plan:

Use Task tool with subagent_type="consulting-expert"
MUST include in prompt: "Save your feedback to [SESSION_DIR]/validation-feedback.md"
Provide path to implementation plan for review
Review proposed approaches objectively
Identify risks and suggest alternatives

Phase 5 - Implement:

Main agent executes directly (NO delegation)
Read plan from [SESSION_DIR]/implementation-plan.md
Use TodoWrite tool to track progress
Follow plan strictly without deviation
Main agent MUST save: [SESSION_DIR]/implementation-complete.md
Ask clarifying questions via AskUserQuestion tool when needed

Phase 6 - Review:

Use Task tool with appropriate review agent for code review
MUST include in prompt: "Save your report to [SESSION_DIR]/quality-report.md"
Provide path to implementation summary
Use Task tool with subagent_type="test-engineer" for testing validation
Compile all feedback from review agents

Phase 7 - Iterate:

Use Task tool with subagent_type="troubleshooter" if issues found (optional)
Provide path to quality report
Address review feedback (main agent)
Return to Phase 6 if significant changes made
Main agent MUST save: [SESSION_DIR]/final-verification.md
Final verification when all checks pass

Progressive Task Tracking

Create todo list at start of implementation phase
Update task status in real-time
Exactly ONE task in_progress at any time
Mark tasks completed immediately upon finishing
Never batch completion updates

Iterative Compliance Validation

CRITICAL Pattern: Validate → If Fail → Reinvoke → Repeat

After EVERY phase, run the validation script:

python .claude/skills/epic/scripts/validate-phase.py <phase> <session-dir>

If validation FAILS:

Identify which required file(s) are missing
Reinvoke the responsible subagent with explicit instruction to create missing file(s)
Re-run validation script
Repeat steps 1-3 until validation PASSES
Do NOT proceed to next phase until validation passes

This iterative flow ensures:

Subagents complete their assigned tasks
All required documentation is created
Compliance is enforced at every phase
No phase can be skipped or incomplete

Session Directory Structure

All subagent reports MUST be saved to: .claude/sessions/[NN]-[session-description]/

Required files by phase:

Phase 1 (Explore): codebase-status.md
Phase 2 (Research): research-report.md
Phase 3 (Plan): implementation-plan.md
Phase 4 (Validate): validation-feedback.md
Phase 5 (Implement): implementation-complete.md
Phase 6 (Review): quality-report.md
Phase 7 (Iterate): final-verification.md

Strict Plan Adherence

Follow the plan exactly as designed
Do not implement beyond defined scope
Do not improvise or add unplanned features
Stop and ask if uncertain about any task
Simple/lean approach over complex solutions

4. Constraints

CRITICAL: Main agent ONLY implements - MUST delegate all other phases (Explore, Research, Plan, Validate, Review, Iterate)
CRITICAL: Follow EXACT phase sequence - Explore → Research → Plan → Validate Plan → Implement → Review → Iterate
CRITICAL: Run validation script after EVERY phase - do NOT proceed until validation PASSES
CRITICAL: If validation fails, MUST reinvoke subagents until they create required files
CRITICAL: Iterative compliance flow is MANDATORY - cannot skip or bypass validation
CRITICAL: All subagent reports MUST be saved to session directory: .claude/sessions/[NN]-[session-description]/
CRITICAL: Use TodoWrite tool throughout implementation to track progress
CRITICAL: Follow plan strictly - no deviation or improvisation
CRITICAL: Do not implement tasks beyond the defined scope
CRITICAL: Mark exactly ONE task as in_progress at a time
CRITICAL: Complete tasks immediately upon finishing (no batching)
Do NOT skip exploration phase - comprehensive context gathering is required
Do NOT skip research phase - research must happen BEFORE planning
Do NOT skip planning phase - thorough strategy development is mandatory
Do NOT skip validation phase - plan must be validated before implementation
Do NOT skip review phase - validation and code review are essential
Do NOT skip iteration phase - feedback must be addressed
Do NOT proceed to next phase if validation fails - reinvoke subagents iteratively
Do NOT create documentation files unless explicitly requested (except required phase reports)
Do NOT add emojis unless user explicitly requests them
Do NOT over-engineer - build for MVP with simple/lean approach
Do NOT implement features, refactoring, or improvements beyond what was asked
Only add comments where logic isn't self-evident
Only validate at system boundaries (user input, external APIs)
Delete unused code completely - no backwards-compatibility hacks
Ask clarifying questions via AskUserQuestion tool when uncertain

5. Success Criteria

Phase 1 - Exploration Success

[ ] Comprehensive codebase context gathered via codebase-explorer agent
[ ] Relevant files and components identified
[ ] Current state and dependencies documented
[ ] Exploration findings reviewed and synthesized

Phase 2 - Research Success

[ ] Research conducted via research-specialist agent
[ ] Complex topics investigated thoroughly
[ ] Approaches validated across multiple sources
[ ] Best practices and patterns identified
[ ] Technical recommendations documented

Phase 3 - Planning Success

[ ] Strategic plan developed via strategic-planner agent
[ ] Problem analyzed comprehensively using exploration and research
[ ] Multiple implementation paths identified
[ ] Trade-offs and risks evaluated
[ ] Consolidated implementation roadmap created
[ ] Success criteria defined

Phase 4 - Validation Success

[ ] Plan reviewed via consulting-expert agent
[ ] Potential risks and over-complications identified
[ ] Pragmatic alternatives suggested where needed
[ ] Plan refined based on validation feedback
[ ] Final implementation strategy approved

Phase 5 - Implementation Success

[ ] Todo list created with all implementation tasks
[ ] All planned tasks executed following specifications
[ ] Code follows established patterns from exploration
[ ] Todos marked as completed immediately after finishing
[ ] No tasks left as in_progress if actually completed
[ ] Implementation decisions documented appropriately
[ ] No features or improvements added beyond scope

Phase 6 - Review Success

[ ] Code review completed via appropriate review agent
[ ] Testing validation performed if tests exist
[ ] All review findings documented
[ ] Issues prioritized by severity
[ ] Feedback compiled for iteration phase

Phase 7 - Iteration Success

[ ] Troubleshooting completed via troubleshooter agent (if needed)
[ ] All review feedback addressed and implemented
[ ] Issues and bugs resolved
[ ] Re-review performed if significant changes made
[ ] No regressions introduced
[ ] Final verification confirms completion

Overall Success

[ ] All seven EPIC phases completed in correct sequence
[ ] Proper delegation to specialized agents for all phases except Implementation
[ ] Main agent handled implementation phase directly
[ ] Research completed BEFORE planning
[ ] Plan validated BEFORE implementation
[ ] Plan followed strictly without deviation
[ ] User requirements fully satisfied
[ ] Code quality validated through review and iteration
[ ] Documentation updated where required

executing-epic-workflow

Executing EPIC Workflow

1. Context

CRITICAL: Session Directory Initialization

2. Workflow

Phase 1: Explore

Phase 2: Research

Phase 3: Plan

Phase 4: Validate Plan

Phase 5: Implement

Phase 6: Review

Phase 7: Iterate

3. Implementation Strategy

Agent Delegation Pattern

Progressive Task Tracking

Iterative Compliance Validation

Session Directory Structure

Strict Plan Adherence

4. Constraints

5. Success Criteria

Phase 1 - Exploration Success

Phase 2 - Research Success

Phase 3 - Planning Success

Phase 4 - Validation Success

Phase 5 - Implementation Success

Phase 6 - Review Success

Phase 7 - Iteration Success

Overall Success