Epic Creation

Epic Creation

Purpose

Create a GitHub epic issue from an implementation plan file, regardless of format or structure.

When to Use

• When writing-plans completes (automatic)
• When user says "create an epic for plan X" (manual)
• When asked to create epics for existing plans

Announce at start: "I'm using the epic-creation skill to create an epic issue."

Input Requirements

• Plan file path (required)
• Force create (optional, default false) - create even if plan already has epic reference

Execution Instructions

Step 1: Read and Understand the Plan

Read the plan file completely. Use your understanding to identify:

• Title/Feature name - What is being implemented?
• Goal - What does it accomplish? (aim for 1 sentence)
• Architecture - How does it work? (aim for 2-3 sentences)
• Tech Stack - What technologies are used?
• Tasks - Major implementation tasks (for checklist)

Flexible reading: Plans may have different formats:

• Superpowers standard format with headers
• Simple numbered lists
• Prose descriptions
• Bullet points
• Other structures

Your job: Extract the essence regardless of format.

Step 2: Check for Existing Epic

PLAN_FILE="<plan-file-path>"

# Check if plan already references an epic
if grep -q "Epic Issue:" "$PLAN_FILE" || grep -q "epic.*#[0-9]" "$PLAN_FILE"; then
  EXISTING_EPIC=$(grep -oP '(?:Epic Issue:|epic).*#\K\d+' "$PLAN_FILE" | head -1)
  echo "⚠️ Plan already linked to epic #$EXISTING_EPIC"
  
  # If not forcing, stop here
  if [ "$FORCE" != "true" ]; then
    echo "Use force=true to create new epic anyway"
    exit 0
  fi
fi

Step 3: Build Epic Body

Create the epic issue body with extracted information:

cat > epic_body.md <<EOF
## 📋 Plan File

\`$PLAN_FILE\`

## 🎯 Goal

$GOAL

## 🏗️ Architecture

$ARCH

## 🛠️ Tech Stack

$TECH

## ✅ Tasks

$TASKS

---

**Status:** 🟡 In Progress

---

## 📚 Implementation Journey

<!-- JOURNEY_START -->

*Journey documentation will be added upon completion.*

<!-- JOURNEY_END -->
EOF

Handling missing information:

• If goal not found: Use "Implementation of [Title]"
• If architecture not found: Use "See plan file for details"
• If tech stack not found: Use "See plan file for details"
• If tasks not found: Use "- [ ] See plan file for task breakdown"

Be practical: Some plans won't have all information clearly labeled. That's okay - extract what you can.

Step 4: Create Epic Issue

# Create the issue
gh issue create \
  --title "$TITLE" \
  --label "epic,planning" \
  --body "$(cat epic_body.md)"

# Capture the issue number
EPIC_NUMBER=$(gh issue list --label "epic" --limit 1 --json number --jq '.[0].number')
echo "Created epic issue: #$EPIC_NUMBER"

Step 5: Update Plan with Epic Reference

Add epic reference to the plan file:

# Add epic reference near the top of the plan (after tech stack if present)
# Find a good insertion point
if grep -q "^\*\*Tech Stack:\*\*" "$PLAN_FILE"; then
  # Insert after tech stack
  sed -i "/^\*\*Tech Stack:\*\*/a\\n**Epic Issue:** #$EPIC_NUMBER" "$PLAN_FILE"
elif grep -q "^---" "$PLAN_FILE"; then
  # Insert after first separator
  sed -i "0,/^---/s/^---/---\n\n**Epic Issue:** #$EPIC_NUMBER/" "$PLAN_FILE"
else
  # Insert after first paragraph/section
  sed -i "4a\\n**Epic Issue:** #$EPIC_NUMBER" "$PLAN_FILE"
fi

# Commit the update
git add "$PLAN_FILE"
git commit -m "docs: link plan to epic issue #$EPIC_NUMBER"

Step 6: Announce

Tell the user:

✅ Epic issue created: #$EPIC_NUMBER
✅ Plan updated with epic reference

Epic URL: https://github.com/<owner>/<repo>/issues/$EPIC_NUMBER

Quality Guidelines

Epic creation should be:

• ✅ Fast - Don't overthink extraction, use common sense
• ✅ Flexible - Handle any reasonable plan format
• ✅ Practical - Missing info? Use sensible defaults
• ✅ Linked - Always update plan with epic reference

Avoid:

• ❌ Rigid format requirements
• ❌ Failing if plan structure is non-standard
• ❌ Over-engineering the extraction logic

Examples

Example 1: Standard Superpowers Plan

Plan structure:

# Feature Implementation Plan

**Goal:** Build the feature
**Architecture:** Uses X and Y
**Tech Stack:** Python, JavaScript

### Task 1: Do thing
### Task 2: Do other thing

Extraction:

• Title: "Feature"
• Goal: "Build the feature"
• Architecture: "Uses X and Y"
• Tech Stack: "Python, JavaScript"
• Tasks: "Task 1: Do thing", "Task 2: Do other thing"

Example 2: Non-Standard Plan

Plan structure:

# Adding Dark Mode

We need to add dark mode to the app. This will involve:

1. Create theme context
2. Add theme toggle
3. Update all components

Technologies: React, CSS-in-JS

Extraction (intelligent reading):

• Title: "Dark Mode"
• Goal: "Add dark mode to the app"
• Architecture: "Create theme context and update all components with dark mode support"
• Tech Stack: "React, CSS-in-JS"
• Tasks: "Create theme context", "Add theme toggle", "Update all components"

Example 3: Minimal Plan

Plan structure:

# Fix Bug #123

Update validation logic to handle edge case.

Extraction (with defaults):

• Title: "Fix Bug #123"
• Goal: "Update validation logic to handle edge case"
• Architecture: "See plan file for details"
• Tech Stack: "See plan file for details"
• Tasks: "- [ ] See plan file for implementation details"

Still useful: Future agents can find this epic and see the linked plan for full context.

Integration

Called by:

• writing-plans skill - After plan is saved
• Manual agent invocation - When user requests epic creation
• Batch operations - When processing multiple plans

Converted and distributed by TomeVault — claim your Tome and manage your conversions.