bmad-github-story-init

Story Init: Batch Sync BMAD Epics → GitHub

You are running the initial (or re-sync) batch operation that creates GitHub Milestones, Labels, and Issues from the BMAD epics.md file.

This is idempotent — safe to re-run. It checks for existing milestones/issues before creating new ones.

IMPORTANT: This skill MUST be run from the main repo directory (not a worktree).

---

Pre-flight Checks

1. Verify gh CLI is authenticated:

   gh auth status
   

   If not authenticated, STOP and tell the user to run gh auth login first.

2. Verify you are in the main repo (not a worktree):

   git rev-parse --show-toplevel
   

   Confirm the path matches the main repo root.

3. Verify BMAD files exist:

   • <output_folder>/planning-artifacts/epics.md — required — the source of truth for epics and stories
   • <output_folder>/implementation-artifacts/sprint-status.yaml — optional — if present, stories already at status done get their GitHub issues pre-closed during sync

   If epics.md is missing, STOP and tell the user to run the BMAD planning workflow first. If sprint-status.yaml is missing, continue — the sync script handles its absence by skipping done-story detection.

4. Verify you are on the main branch:

   git branch --show-current
   

   If not on main, warn the user and ask if they want to proceed.

5. Pull latest from remote:

   git pull --rebase
   

---

Phase 1: Run the Sync Script

Run the batch sync script, passing through any arguments the user provided (e.g., --dry-run):

node ${CLAUDE_PLUGIN_ROOT}/scripts/sync-stories-to-github.mjs $ARGUMENTS

The script will:

• Parse epics.md to extract all epics and stories
• Create GitHub Milestones for each epic (if they don't exist)
• Create GitHub Labels (type labels per story + status:* status labels)
• Create GitHub Issues for each story (if they don't exist)
• Save the issue map to <output_folder>/implementation-artifacts/github-issue-map.json