epic-start

Prompt file imported from YNK0/Boreas (.claude/commands/oden/epic-start.md). Fill in {{arguments}} before use. Copyright stays with the author.

Epic Start

Launch parallel agents to work on epic tasks in a shared branch.

Usage

/pm:epic-start <epic_name>

Quick Check

1. Verify epic exists:

   test -f .claude/epics/{{arguments}}/epic.md || echo "❌ Epic not found. Run: /pm:prd-parse {{arguments}}"

2. Check GitHub sync: Look for github: field in epic frontmatter. If missing: "❌ Epic not synced. Run: /pm:epic-sync {{arguments}} first"

3. Check for branch:

   git branch -a | grep "epic/{{arguments}}"

4. Check for uncommitted changes:

   git status --porcelain

   If output is not empty: "❌ You have uncommitted changes. Please commit or stash them before starting an epic"

Instructions

1. Create or Enter Branch

Follow /rules/branch-operations.md:

# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "❌ You have uncommitted changes. Please commit or stash them before starting an epic."
  exit 1
fi

# If branch doesn't exist, create it
if ! git branch -a | grep -q "epic/{{arguments}}"; then
  git checkout main
  git pull origin main
  git checkout -b epic/{{arguments}}
  git push -u origin epic/{{arguments}}
  echo "✅ Created branch: epic/{{arguments}}"
else
  git checkout epic/{{arguments}}
  git pull origin epic/{{arguments}}
  echo "✅ Using existing branch: epic/{{arguments}}"
fi

2. Identify Ready Issues

Read all task files in .claude/epics/{{arguments}}/:

• Parse frontmatter for status, depends_on, parallel fields
• Check GitHub issue status if needed
• Build dependency graph

Categorize issues:

• Ready: No unmet dependencies, not started
• Blocked: Has unmet dependencies
• In Progress: Already being worked on
• Complete: Finished

3. Analyze Ready Issues

For each ready issue without analysis:

# Check for analysis
if ! test -f .claude/epics/{{arguments}}/{issue}-analysis.md; then
  echo "Analyzing issue #{issue}..."
  # Run analysis (inline or via Task tool)
fi

4. Launch Parallel Agents

For each ready issue with analysis:

## Starting Issue #{issue}: {title}

Reading analysis...
Found {count} parallel streams:
  - Stream A: {description} (Agent-{id})
  - Stream B: {description} (Agent-{id})

Launching agents in branch: epic/{{arguments}}

Use Task tool to launch each stream:

Task:
  description: "Issue #{issue} Stream {X}"
  subagent_type: "{agent_type}"
  prompt: |
    Working in branch: epic/{{arguments}}
    Issue: #{issue} - {title}
    Stream: {stream_name}

    Your scope:
    - Files: {file_patterns}
    - Work: {stream_description}

    Read full requirements from:
    - .claude/epics/{{arguments}}/{task_file}
    - .claude/epics/{{arguments}}/{issue}-analysis.md

    Follow coordination rules in /rules/agent-coordination.md

    Commit frequently with message format:
    "Issue #{issue}: {specific change}"

    Update progress in:
    .claude/epics/{{arguments}}/updates/{issue}/stream-{X}.md

5. Track Active Agents

Create/update .claude/epics/{{arguments}}/execution-status.md:

---
started: {datetime}
branch: epic/{{arguments}}
---

# Execution Status

## Active Agents
- Agent-1: Issue #1234 Stream A (Database) - Started {time}
- Agent-2: Issue #1234 Stream B (API) - Started {time}
- Agent-3: Issue #1235 Stream A (UI) - Started {time}

## Queued Issues
- Issue #1236 - Waiting for #1234
- Issue #1237 - Waiting for #1235

## Completed
- {None yet}

6. Monitor and Coordinate

Set up monitoring:

echo "
Agents launched successfully!

Monitor progress:
  /pm:epic-status {{arguments}}

View branch changes:
  git status

Stop all agents:
  /pm:epic-stop {{arguments}}

Merge when complete:
  /pm:epic-merge {{arguments}}
"

7. Handle Dependencies

As agents complete streams:

• Check if any blocked issues are now ready
• Launch new agents for newly-ready work
• Update execution-status.md

Output Format

🚀 Epic Execution Started: {{arguments}}

Branch: epic/{{arguments}}

Launching {total} agents across {issue_count} issues:

Issue #1234: Database Schema
  ├─ Stream A: Schema creation (Agent-1) ✓ Started
  └─ Stream B: Migrations (Agent-2) ✓ Started

Issue #1235: API Endpoints
  ├─ Stream A: User endpoints (Agent-3) ✓ Started
  ├─ Stream B: Post endpoints (Agent-4) ✓ Started
  └─ Stream C: Tests (Agent-5) ⏸ Waiting for A & B

Blocked Issues (2):
  - #1236: UI Components (depends on #1234)
  - #1237: Integration (depends on #1235, #1236)

Monitor with: /pm:epic-status {{arguments}}

Error Handling

If agent launch fails:

❌ Failed to start Agent-{id}
  Issue: #{issue}
  Stream: {stream}
  Error: {reason}

Continue with other agents? (yes/no)

If uncommitted changes are found:

❌ You have uncommitted changes. Please commit or stash them before starting an epic.

To commit changes:
  git add .
  git commit -m "Your commit message"

To stash changes:
  git stash push -m "Work in progress"
  # (Later restore with: git stash pop)

If branch creation fails:

❌ Cannot create branch
  {git error message}

Try: git branch -d epic/{{arguments}}
Or: Check existing branches with: git branch -a

Important Notes

• Follow /rules/branch-operations.md for git operations
• Follow /rules/agent-coordination.md for parallel work
• Agents work in the SAME branch (not separate branches)
• Maximum parallel agents should be reasonable (e.g., 5-10)
• Monitor system resources if launching many agents