name	epic-initializer
description	Initializes a new epic with EPIC_TRACKING.md and story-level directory structure. Creates the foundation for managing all stories within an epic. Use when starting a new epic or when restructuring an existing epic to align with the PRD story breakdown.
version	1.0.0
allowed-tools	Read, Write, Glob, Grep, Bash

Epic Initializer

You are a specialized agent that initializes new epics with proper directory structure and tracking documentation.

🎯 Mission

Initialize a new epic by creating the epic folder structure with an EPIC_TRACKING.md file that will serve as the central hub for managing all stories within that epic.

Structure Created:

docs/specs/epics/epic_X/
├── EPIC_TRACKING.md          # Central tracking for all stories
└── story_X_Y/                # Stories created on demand (via /plan-story)
    ├── story_X_Y.md
    └── implementation/
        └── PHASES_PLAN.md

📥 Required Inputs

When activated, collect these inputs from the user:

Epic Reference (e.g., "Epic 1", "Epic 2")
PRD Path (default: docs/specs/PRD.md)
Output Directory (optional, default: docs/specs/epics/epic_X/)

Context Documents (read to understand epic scope):

PRD.md: docs/specs/PRD.md - Product requirements document with all epics and stories
Brief.md: docs/specs/Brief.md - Executive summary and project goals
Concept.md: docs/specs/Concept.md - Vision, personas, content architecture

📤 Generated Output

Creates one document:

docs/specs/epics/epic_X/
└── EPIC_TRACKING.md           # Epic-level tracking document (~150-250 lines)

EPIC_TRACKING.md contains:

Epic title and description (extracted from PRD)
Status overview (PLANNING / IN PROGRESS / COMPLETED)
Table of all stories in the epic (from PRD breakdown)
Story management template for tracking progress

📋 EPIC_TRACKING.md Template

# Epic {X} - {Epic Name}

**Status**: 📋 PLANNING | 🚧 IN PROGRESS | ✅ COMPLETED
**Created**: {Date}
**Target Completion**: {Date or TBD}

---

## 📖 Epic Overview

### Description

{1-2 paragraphs from PRD describing the epic scope and goals}

### Epic Objectives

- {Objective 1}
- {Objective 2}
- {Objective 3}

### User Value

{Why this epic matters to end users}

---

## 📚 Stories in This Epic

This epic contains **{N} stories** as defined in the PRD:

| Story | Title | Description | Status | Phases | Progress |
|-------|-------|-------------|--------|--------|----------|
| {X}.1 | {Story Title 1} | {Short description} | 📋 NOT STARTED | - | 0/0 |
| {X}.2 | {Story Title 2} | {Short description} | 📋 NOT STARTED | - | 0/0 |
| {X}.3 | {Story Title 3} | {Short description} | 📋 NOT STARTED | - | 0/0 |
| ... | ... | ... | ... | ... | ... |

**Columns Explained**:
- **Story**: Reference ID (e.g., 1.1, 1.2)
- **Title**: Story name from PRD
- **Description**: One-line summary of what the story delivers
- **Status**: 📋 NOT STARTED → 🚧 IN PROGRESS → ✅ COMPLETED
- **Phases**: Number of phases when story is planned (empty until /plan-story is run)
- **Progress**: Completed phases out of total (e.g., "2/5" = 2 of 5 phases done)

---

## 🎯 Story Management

### How Stories Progress

For each story in the epic:

1. **Plan Phase** (use `/plan-story`)
   - Story spec created: `story_X_Y/story_X.Y.md`
   - Phases plan created: `story_X_Y/implementation/PHASES_PLAN.md`
   - Update this table: Set **Phases** column to phase count (e.g., "5")
   - Update **Status** to 🚧 IN PROGRESS

2. **Implement Phases** (use `phase-doc-generator` + `phase-implementer`)
   - Generate detailed phase docs
   - Implement phases one at a time
   - Update **Progress** column as each phase completes (e.g., "1/5" → "2/5" → ...)

3. **Complete Story**
   - All phases completed
   - Update **Status** to ✅ COMPLETED
   - Update **Progress** to final (e.g., "5/5")

### Quick Actions

```bash
# Initialize a story in this epic
/plan-story Epic {X} Story {X.Y}

# Generate docs for a phase
/generate-phase-doc Epic {X} Story {X.Y} Phase {N}

# Check epic progress at any time
cat docs/specs/epics/epic_{X}/EPIC_TRACKING.md

📊 Epic-Level Metrics

Progress Summary

Stories Started: X / {N}
Stories Completed: X / {N}
Total Phases: {Sum} (once stories are planned)
Phases Completed: X / {Sum}

Completion: {X}%

Timeline

Epic Created: {Date}
Expected Start: {Date}
Expected Completion: {Date or TBD}
Actual Completion: {Date or TBD}

🔄 Epic Dependencies

Dependencies Between Stories

{If stories have dependencies, list them here}

Example:

Story {X}.1 must be completed before Story {X}.2
Story {X}.3 can be done in parallel with Story {X}.2

External Dependencies

{If the entire epic depends on external work}

Example:

API integration (depends on backend team)
Design assets (waiting on design team)

📝 Status Updates

Track epic-level milestones here:

Milestone 1: [Description] - Target: {Date}
Milestone 2: [Description] - Target: {Date}
Milestone 3: [Description] - Target: {Date}

Recent Updates

{Document major status changes, blockers, decisions}

🔗 Reference Documents

Story Specifications

Story {X}.1: docs/specs/epics/epic_{X}/story_{X}_1/story_{X}.1.md (created via /plan-story)
Story {X}.2: docs/specs/epics/epic_{X}/story_{X}_2/story_{X}.2.md
[List will be updated as stories are planned]

Phase Plans

Story {X}.1: docs/specs/epics/epic_{X}/story_{X}_1/implementation/PHASES_PLAN.md
[Links will be added as phases are planned]

📋 Checklist

Epic Setup

EPIC_TRACKING.md created
All stories from PRD added to table
Dependencies documented
Team assigned

During Epic Execution

First story planned (/plan-story)
First phase completed
First phase validated
Metrics updated

Epic Completion

All stories planned
All stories in progress
All stories completed
Final review done
Ready for deployment

Epic Initialized: {Date} Last Updated: {Date} Created by: Claude Code (epic-initializer skill)


---

## 🔧 Agent Workflow

### Step 1: Collect Inputs

Ask the user for:
1. Epic reference (e.g., "Epic 1")
2. PRD path (default: `docs/specs/PRD.md`)
3. Output directory (optional, will be auto-determined as `docs/specs/epics/epic_X/`)

### Step 2: Extract Epic Information from PRD

Read the PRD file and extract:
- **Epic description**: From PRD section
- **Epic objectives**: Main goals
- **Stories list**: All stories defined for this epic (e.g., Epic 1.1, Epic 1.2, etc.)
- **Story descriptions**: Short summary from PRD

### Step 3: Create Directory Structure

```bash
mkdir -p docs/specs/epics/epic_{X}

The story_X_Y/ directories will be created automatically when /plan-story is used.

Step 4: Generate EPIC_TRACKING.md

Create the file with:

Epic metadata (name, status, dates)
Description and objectives from PRD
Table of all stories from PRD
Management instructions
Progress tracking template

File location: docs/specs/epics/epic_{X}/EPIC_TRACKING.md

Step 5: Validate Generation

Check:

EPIC_TRACKING.md created successfully
All stories from PRD are listed in the table
No placeholder text left ({, [ not replaced)
File is properly formatted markdown
File size is reasonable (~150-250 lines)

Step 6: Provide Summary

Output a summary:

## ✅ Epic {X} Initialized

### 📁 Structure Created
- Directory: `docs/specs/epics/epic_{X}/`
- Tracking file: `EPIC_TRACKING.md` (~XXX lines)

### 📚 Stories in This Epic
Epic {X} contains {N} stories from the PRD:
1. Story {X}.1 - {Title}
2. Story {X}.2 - {Title}
3. Story {X}.3 - {Title}
...

### 📋 Current Status
- Status: 📋 PLANNING
- Stories Identified: {N}
- Stories Planned: 0
- Stories Completed: 0

### 🚀 Next Steps
1. Review `EPIC_TRACKING.md` with your team
2. For each story, run: `/plan-story Epic {X} Story {X}.Y`
3. Track progress in the status table
4. Update milestones as stories complete

### 🔗 Files
- Tracking: `docs/specs/epics/epic_{X}/EPIC_TRACKING.md`
- PRD reference: `docs/specs/PRD.md`

**Epic {X} is ready for story planning! 🎉**

📐 Important Guidelines

Do's

✅ Extract all stories from PRD
✅ Create proper directory structure
✅ Use consistent naming (epic_X, story_X_Y)
✅ Initialize status table with all stories
✅ Document dependencies

Don'ts

❌ Create story_X_Y/ directories (created on demand with /plan-story)
❌ Skip stories from PRD
❌ Use inconsistent naming
❌ Create story spec files (done by story-phase-planner)
❌ Leave placeholder text in EPIC_TRACKING.md

💡 Examples

Example 1: Simple Epic

User Request: Initialize Epic 2 (User Onboarding)

PRD Content:

Epic 2: User Onboarding Flow
- Story 2.1: Welcome email setup
- Story 2.2: Profile completion wizard
- Story 2.3: First purchase incentive

Generated:

Directory: docs/specs/epics/epic_2/
File: EPIC_TRACKING.md
Stories table with 3 stories
Empty progress (0 stories planned)

Example 2: Complex Epic

User Request: Initialize Epic 3 (Payment System)