---
roadcrew_template_name: "create-epic.md"
roadcrew_template_type: "command"
roadcrew_template_version: "v1.0"
roadcrew_last_updated: "2025-10-25"
roadcrew_min_version: "1.5.0"
roadcrew_license: "See LICENSE file in .roadcrew folder"
roadcrew_copyright: "Copyright (c) 2025 North Star Holdings, LLC"
spdx_license_identifier: "LicenseRef-RoadcrewLicense-1.0"
execution_mode: "auto-execute"
---

# create-epic

Create a GitHub Epic in batch mode from a spec.

> **Execution:** Runs immediately with automatic issue generation. No approval pauses.

**Prerequisites:** Spec must exist and be valid. Run `/create-spec` first if needed.

<!-- Usage: /create-epic -->

Convert specification documents, chat discussions, or current context into structured GitHub epics with child issues using templates and proper linkages. Supports multiple input sources: parse technical specs, extract epics from chat history, or analyze current discussion.

**Purpose:** Prepare you to run `/autopilot` by converting specifications or conversations into GitHub work with complete specifications and complexity scoring.

**Enhancements (PR #884):** Added support for spec document parsing and chat history extraction with objective task complexity framework integration, generating issue classifications and dimension-based assignment recommendations.

**Prerequisites:** GitHub authentication required. See `commands/README.md` (§ GitHub Authentication) for setup: GitHub API via Personal Access Token (primary method), GitHub CLI (fallback).

---

## 🔒 CRITICAL POLICY: GitHub-First, No Interim Documentation

**`/create-epic` MUST ALWAYS:**
- ✅ **Create ALL epics and issues directly in GitHub** - Never create interim .md documentation files
- ✅ **Use @epic.template.md and @enhancement.template.md** - ALWAYS load and use these templates for all issues
- ✅ **Use GitHub API or SSH** - Primary method for all operations
- ✅ **Verify every issue was created** - Extract and confirm GitHub issue numbers for Epic and all Child Issues
- ✅ **Apply full template population** - No template variables remain in created issues
- ✅ **Ready for /autopilot immediately** - No additional enrichment needed

**`/create-epic` MUST NEVER:**
- ❌ **Create interim documentation files** (e.g., `memory-bank/requirements/source-docs/epic-*.md`, temporary files)
- ❌ **Create placeholder files** (e.g., `.md` files as stepping stones)
- ❌ **Leave template variables** in GitHub issues (e.g., `{{GITHUB_ISSUE_NUMBER}}`, `<!-- TODO: enrich -->`)
- ❌ **Skip template loading** - ALWAYS use @epic.template.md and @enhancement.template.md
- ❌ **Hardcode issue bodies** - Populate templates with variables, then create
- ❌ **Defer specification details** - All details populated before creating GitHub issues
- ❌ **Complete without verifying** all issues exist in GitHub with proper issue numbers
- ❌ **Create files in context/, templates/, or docs/** - All work created in GitHub only

**Verification Checkpoints:**
```
BEFORE completing /create-epic:

1. ✅ Epic issue created in GitHub? Does it have a GitHub issue number (#NNN)?
2. ✅ All child issues created? Does each have a GitHub issue number (#NNN)?
3. ✅ Issue numbers recorded? Displayed to user?
4. ✅ No interim files? Check git status for new .md files
5. ✅ Full enrichment applied? No <!-- TODO: enrich --> markers remain?
6. ✅ All template variables replaced? No {{...}} remain in issues?

If ANY check fails → STOP and report error. Do not complete /create-epic.
```

---

## 📊 Workflow: Analyze → Propose → Approve → Create (GitHub Only)

### Phase 1: Conversation Analysis

**Parse chat context:**
1. Extract all requirements discussed
2. Identify feature requests and tasks
3. Track dependencies mentioned
4. Note priorities and constraints
5. Measure scope: complexity, estimated hours

**Classify scope:**
- **Small (Single Issue):** Single concern, 1-3 files, no dependencies, 1-6 hours
- **Medium (Epic with 2-4 Issues):** Related concerns, 1-2 dependencies, 4-12 hours
- **Large (Epic with 5-8 Issues):** Multiple subsystems, 3+ dependencies, 12-24 hours

### Phase 2: Proposal Generation

Display proposal structure with classification (1-10 scale) and estimated effort.

**Include:**
- Epic title and overview
- Issue count and breakdown
- Dependencies between issues
- Estimated total hours
- Classification distribution (ai-solo/led/assisted/limited)
- Clear rationale

### Phase 3: User Approval

**Options:**
1. Approve proposed structure
2. Reject and discuss further
3. Request modifications

### Phase 4: GitHub Issue Creation (Unified Module)

**The `/create-epic` command uses the unified GitHub issue creator module:**

```typescript
import { createEpicIssue, createEnhancementIssue } from './core/github-issue-creator.js';

// Create epic using unified module
const epicResult = await createEpicIssue(epicTitle, epicBody);
const epicNumber = epicResult.number;

// Create child issues using unified module
for (let i = 0; i < issues.length; i++) {
  const issue = issues[i];
  const childResult = await createEnhancementIssue(
    issue.title,
    issue.body,
    i + 1,
    issues.length
  );
  childNumbers.push(childResult.number);
}
```

**Benefits of Unified Module:**
- ✅ **Resilience:** Automatic API + CLI fallback on failure
- ✅ **Security:** Safe shell escaping built-in
- ✅ **Reliability:** Duplicate detection and closure
- ✅ **Multi-repo:** Supports cross-repo issue creation
- ✅ **GitHub Projects v2:** Automatic integration
- ✅ **Test Coverage:** 50+ automated test cases

**Internal Details (No Manual Implementation):**
- Automatically extracts issue numbers from GitHub response
- Automatically verifies issues were created
- Automatically handles all API/CLI interactions
- No need for manual `parseIssueNumber()` or `verifyIssueExists()`

**You don't need to implement this yourself** - use the `/create-epic` command which handles all the details internally.

### Phase 5: Verification

**Verify all issues created:**
```bash
gh issue view #XXX --json number,title,labels
```

**Expected output:** All issues exist with correct issue numbers.

**If verification fails:**
```
❌ VERIFICATION FAILED

Issue #XXX exists in GitHub but [problem description]

ACTION REQUIRED: [specific fix needed]
```

---

## 🎯 Command Execution

This command runs the TypeScript script:
- **Instance installation:** `scripts/create-epic.ts`
- **Submodule installation:** `.roadcrew/scripts/create-epic.ts`

**Flags:**
- `--auto` - Skip proposal approval and create immediately (beta)
- `--spec <path>` - Parse technical specification document and extract epic structure (NEW: PR #884)
- No flag - Interactive mode (analyze → propose → approve → create)

**Behavior:**
- Analyzes current Cursor chat
- Proposes epic with child issues
- Requests user approval
- Creates ALL issues directly in GitHub
- Displays verification results

---

## 📋 Template Variables

**Epic Variables (from @epic.template.md):**
- EPIC_TITLE, EPIC_NUMBER, EPIC_OVERVIEW
- GOAL_1 through GOAL_5
- CHILD_ISSUES_LIST
- DEPENDENCY_EPICS, BLOCKED_EPICS
- RELEASE_GITHUB_ISSUE, RELATED_SPEC
- ASSIGNEES

**Issue Variables (from @enhancement.template.md):**
- ISSUE_NUMBER, TOTAL_ISSUES
- ENHANCEMENT_TITLE, COLOR_BALL
- OVERVIEW, ACCEPTANCE_CRITERIA
- TECHNICAL_IMPLEMENTATION
- DEPENDENCIES
- ISSUE_SIZE, COMPLEXITY, CLASSIFICATION
- TASK_PROFILE_DIMENSIONS: determinism, contextBreadth, verificationCost, domainKnowledge (NEW: PR #884)
- ASSIGNMENT_RECOMMENDATIONS: resource options with confidence levels (NEW: PR #884)
- EPIC_NUMBER, SPEC_NAME, SPEC_FILE
- ASSIGNEES

**All variables populated BEFORE GitHub creation - no placeholders in issues.**

---

## ⚠️ Anti-Patterns (NEVER DO)

❌ **DON'T:** Create `.md` files as intermediate steps
✅ **DO:** GitHub API directly

❌ **DON'T:** Use `gh issue create --body-file issue.md` pattern
✅ **DO:** Pass `--body "..."` with full content

❌ **DON'T:** Leave template variables in GitHub issues
✅ **DO:** Substitute all variables before creating

❌ **DON'T:** Create files in context/ for future enrichment
✅ **DO:** Enrich in memory, create fully-populated GitHub issues

❌ **DON'T:** Ask user to fill in details later
✅ **DO:** Extract all details from conversation first

---

## Success Output

```
✅ ISSUES CREATED SUCCESSFULLY

Epic #905: [Epic Title]
├─ #906: [Issue 1 Title]
├─ #907: [Issue 2 Title]
├─ #908: [Issue 3 Title]
└─ #909: [Issue 4 Title]

Next Steps:
  1. Review: https://github.com/[org]/[repo]/issues/905
  2. Run: /autopilot 905 (to implement the epic)

Verification: ✅ ALL ISSUES CREATED IN GITHUB
  • Epic #905: ✅ VERIFIED
  • Issues #906-909: ✅ ALL VERIFIED
  • No interim files created: ✅ VERIFIED
```

---

## Error Handling

**GitHub Authentication Failed:**
```
❌ GitHub authentication required
See commands/README.md (§ GitHub Authentication) for setup:
1. Primary: Set GH_TOKEN environment variable with GitHub Personal Access Token
2. Fallback: Configure GitHub CLI (`gh auth login`)
Then re-run: /create-epic
```

**Issue Creation Failed:**
```