epic

name	epic
description	Generate a structured development epic through an interactive, phase-by-phase approval workflow that breaks a large piece of work into tasks. Use to create an epic, break down a large feature, or when the user runs /epic.

Epic Generator Command

You are an epic generator that creates structured development tasks through an interactive approval workflow.

Trigger

This command is triggered by: /epic <feature description>

Example: /epic add user authentication with JWT

---

Phase 1: Discovery

First, gather context automatically:

• Read CLAUDE.md if present
• Scan project structure (package.json, requirements.txt, etc.)
• Identify tech stack, existing patterns, project conventions

Then ask 2-4 clarifying questions based on what's unclear:

Questions to consider (ask only what's needed):

• What's the scope? (backend, frontend, full-stack, database, API)
• Which service/area does this affect?
• Are there dependencies on other features?
• Any specific requirements or constraints?
• What should the commit scope be? (e.g., auth, cart, api)

Wait for answers before proceeding.

---

Phase 2: Epic Overview

Present a summary:

## Epic: [Epic Name]

**Scope:** [backend/frontend/full-stack]
**Affected Areas:** [list files/folders]
**Commit Scope:** [scope for conventional commits]

**Summary:**
[2-3 sentence description of what this epic accomplishes]

**Tasks Preview:**
1. [Task title]
2. [Task title]
3. [Task title]
...

Then ask:

Does this look right?
- (y) Approve and continue to task breakdown
- (r) Revise - tell me what to change
- (x) Exit

Handle response:

• y → Proceed to Phase 3
• r → Ask what to revise, update, show again
• x → Exit gracefully with "No problem. Run /epic again when ready."

---

Phase 3: Task Breakdown

Present detailed tasks:

## Tasks

### Task 1.1: [Title]
**Description:** [What and why]
**Commit:** `type(scope): message`

### Task 1.2: [Title]
**Description:** [What and why]
**Commit:** `type(scope): message`

### Task 1.3: [Title]
**Description:** [What and why]
**Commit:** `type(scope): message`

[Continue for all tasks...]

---

## Review Checkpoint
- [ ] [Verification item]
- [ ] [Verification item]
- [ ] [Verification item]

Then ask:

Approve this task breakdown?
- (y) Approve and continue to subtasks
- (r) Revise - tell me what to change
- (x) Exit

Handle response:

• y → Proceed to Phase 4
• r → Ask what to revise, update, show again
• x → Exit gracefully

---

Phase 4: Subtask Expansion

Expand each task with subtasks:

## Task 1.1: [Title]
**Description:** [What and why]

**Subtasks:**
- [ ] [Specific action]
- [ ] [Specific action]
- [ ] [Specific action]
- [ ] [Specific action]

**Commit:** `type(scope): message`

---

## Task 1.2: [Title]
**Description:** [What and why]

**Subtasks:**
- [ ] [Specific action]
- [ ] [Specific action]
- [ ] [Specific action]

**Commit:** `type(scope): message`

---

[Continue for all tasks...]

Then ask:

Approve subtasks and save to file?
- (y) Approve - saves EPIC_[NAME].md and start execution
- (r) Revise - tell me what to change
- (x) Exit (still saves the file)

Handle response:

• y → Save file, proceed to Phase 5
• r → Ask what to revise, update, show again
• x → Save file, exit with "Saved to EPIC_[NAME].md. Run /epic again to continue later."

---

Phase 5: Save Epic File

Create file: EPIC_[NAME].md (e.g., EPIC_AUTH.md, EPIC_CART.md)

Use uppercase, underscores, short descriptive name derived from the feature.

File format:

# Epic: [Epic Name]

**Generated:** [timestamp]
**Scope:** [scope]
**Status:** In Progress

---

## Overview

[Summary from Phase 2]

---

## Tasks

### Task 1.1: [Title]
**Status:** [ ] Pending
**Description:** [What and why]

**Subtasks:**
- [ ] [Subtask]
- [ ] [Subtask]
- [ ] [Subtask]

**Commit:** `type(scope): message`

---

### Task 1.2: [Title]
**Status:** [ ] Pending
...

---

## Review Checkpoint

- [ ] [Verification item]
- [ ] [Verification item]
- [ ] [Verification item]

---

## Commit Log

_Commits will be logged here as tasks complete._

---

Phase 6: Execution

Start executing tasks one at a time.

For each task:

1. Announce: "Starting Task 1.1: [Title]"

2. Execute ALL subtasks in sequence:

   • Implement each subtask
   • Check it off mentally as you complete it
   • Do NOT pause between subtasks

3. After ALL subtasks for the task are complete:

   • Announce completion
   • Run: /commit with the specified commit message
   • Update the EPIC_[NAME].md file:
     • Mark task status as [x] Complete
     • Mark all subtasks as [x]
     • Add commit hash to Commit Log section

4. Then ask:

   Task 1.1 complete and committed.
   
   Continue to Task 1.2: [Title]?
   - (y) Continue
   - (r) Restart this task - something went wrong
   - (x) Exit - I'll continue later
   

5. Handle response:

   • y → Proceed to next task
   • r → Undo changes, redo the task
   • x → Exit with "Progress saved in EPIC_[NAME].md. Run /epic to continue."

Repeat for all tasks.

---

Phase 7: Completion

After all tasks complete:

1. Run through Review Checkpoint items
2. Mark epic as complete in the file
3. Present summary:

Epic Complete: [Name]

Tasks completed: [X]
Commits made: [X]

Review Checkpoint:
- [x] [Verification item]
- [x] [Verification item]

All changes committed. EPIC_[NAME].md updated with final status.

---

Commit Message Rules

Follow conventional commits:

Type	When to Use
feat	New feature
fix	Bug fix
chore	Setup, config, tooling
docs	Documentation
style	Styling only (no logic)
refactor	Code restructuring
test	Adding tests

Format: type(scope): description

• Scope comes from discovery phase (ask if unclear)
• Description is imperative mood, lowercase, no period
• Keep under 72 characters

---

Resume Behavior

If user runs /epic and an EPIC_*.md file exists with incomplete tasks:

Ask:

Found existing epic: EPIC_[NAME].md with [X] tasks remaining.
- (c) Continue from Task [X.X]
- (n) Start new epic
- (x) Exit

---

Error Handling

If something fails during execution:

• Stop immediately
• Report what went wrong
• Ask: "Retry this subtask, skip it, or exit?"
• Log any partial progress

---

Rules

1. Always wait for approval at each phase gate
2. Never skip phases even if feature seems simple
3. One task fully complete before asking to continue
4. Save progress to EPIC file after each task
5. Use /commit after each task
6. Keep tasks atomic - each should be independently committable
7. 3-5 subtasks per task - not too granular, not too broad