github-sync

What this skill does

# GitHub Sync — BMAD to GitHub Projects v2

Bidirectional sync between BMAD planning artifacts (epics, stories, sprint plan) stored as
markdown files and GitHub Projects v2 for visual project tracking.

> **Quick navigation**
> - `gh` CLI commands, GraphQL queries → `references/gh-commands.md`
> - Issue body template, field mapping, labels, milestones → `references/content-mapping.md`
> - Config file format → `references/config-schema.md`
> - Artifact parser script → `scripts/parse-artifacts.py`

---

## Four Rules (Never Break These)

1. **Never sync automatically.** Every mutating operation (create issues, update fields, modify
   files) requires generating a sync report first, presenting it to the user, and waiting for
   explicit approval before executing. The user must see exactly what will change.

2. **Field-level source of truth.** Each field has one owner — either BMAD files or GitHub.
   During sync, the owner side always wins. Never overwrite the owner's data.
   - **BMAD owns:** story body, acceptance criteria, tasks, sprint assignment, epic grouping, dependencies
   - **GitHub owns:** status, dev assignment, task checkbox completion, story points, priority

3. **Idempotent operations.** Running the same sync twice produces the same result. Link-back
   identifiers (H1 title links in story files, `gh_item_url` in planning frontmatter) prevent
   duplicate creation. Always check for existing sync state before creating.

4. **Never auto-parse issue bodies with a script.** Issue body generation requires reading each
   story file directly with the Read tool and crafting the body manually following the template
   in `references/content-mapping.md`. Auto-parsing scripts fail silently in subtle ways:
   they strip task lists when formatting assumptions are wrong, gut dev notes by removing code
   blocks, and produce empty section headers. One bad push contaminates all 27 issues at once.
   **Read the file. Write the body. No shortcuts.**

---

## Flow Detection

| User Says | Workflow | Config Required? |
|-----------|----------|-----------------|
| "set up github project", "onboard", "initialize github" | **Onboarding** | No (creates config) |
| "push to github", "sync push", "create issues" | **Push** | Yes |
| "pull from github", "sync pull", "update from github" | **Pull** | Yes |
| "sync status", "what's out of sync" | **Status Check** | Yes |

**If no `.github-sync.yaml` exists at project root, always route to Onboarding first.**

---

## Prerequisite Check (Run Before Every Workflow)

Before any workflow, verify these in order. Stop at first failure.

```
Step 1: gh --version
        → If missing: "Install GitHub CLI: https://cli.github.com/"

Step 2: gh auth status
        → If not authenticated: "Run: gh auth login"

Step 3: gh auth status (check for "project" in scopes)
        → If missing: "Run: gh auth refresh -s project"

Step 4: (For push/pull/status only) Check .github-sync.yaml exists
        → If missing: "Run onboarding first: say 'set up github project'"
```

---

## Onboarding Workflow

This is the first-time setup. It creates or connects to a GitHub Project, creates custom
fields, labels, and phase-based milestones.

### Step 1: Detect BMAD Artifacts

Run the parser to discover what exists:

```bash
python3 .agents/skills/github-sync/scripts/parse-artifacts.py --mode scan \
  --stories-dir .artifacts/implementation-artifacts
```

Also check that these files exist:
- `.artifacts/planning-artifacts/epics.md`
- `.artifacts/planning-artifacts/sprint-plan.md`

> **Note:** The artifacts path `.artifacts/` may differ per project. Check the actual
> directory structure — some projects use `_bmad-output/`. Confirm the correct paths with
> the user and use them throughout. Update `paths.*` in the config accordingly.

Report the count: "Found N story files, M epics, K sprints."

### Step 2: Gather GitHub Details

Auto-detect the current repo:
```bash
gh repo view --json owner,name --jq '.owner.login + "/" + .name'
```

List existing projects and ask the user whether to use one or create new:
```bash
gh project list --owner {owner} --format json
```

Present detected owner/repo and existing projects. Ask for confirmation before proceeding.

### Step 3: Parse Epic and Sprint Data

**Read `references/content-mapping.md` now** — sections 7 (Label Scheme), 8 (Milestone Scheme),
and 12 (Epic Derivation). You need these to build an accurate onboarding report.

Then parse the actual artifacts:

```bash
python3 .agents/skills/github-sync/scripts/parse-artifacts.py --mode epics \
  --file .artifacts/planning-artifacts/epics.md

python3 .agents/skills/github-sync/scripts/parse-artifacts.py --mode sprints \
  --file .artifacts/planning-artifacts/sprint-plan.md
```

### Step 4: Generate Onboarding Report

Present a report showing everything that WILL be created:

```
=== GITHUB SYNC — ONBOARDING REPORT ===

Repository: {owner}/{repo}
Project: #{N} "{title}" (existing) OR new project "{title}"

Will create/verify:
  Custom fields (7):
    - Story ID      (TEXT)
    - Epic          (SINGLE_SELECT: 12 options, rainbow colors)
    - Sprint        (SINGLE_SELECT: Sprint 01–12, rainbow colors + sprint goal descriptions)
    - Dev           (SINGLE_SELECT: All, Dev 1, Dev 2, Dev 3, Dev 1+2)
    - Sprint Start  (DATE)
    - Sprint End    (DATE)
    - Story Points  (NUMBER)
  Built-in fields to set:
    - Start date    (DATE, pre-existing)   ← same dates as Sprint Start
    - Target date   (DATE, pre-existing)   ← same dates as Sprint End
    - Status        (single-select, pre-existing)
  {N} labels:
    - Epic labels (one per epic, e.g., epic:1-foundation ... epic:12-testing)
    - Phase labels (e.g., phase:poc, phase:hardening)
    - Layer labels (optional, project-specific architecture layers)
  {K} milestones (phase-based, NOT per-sprint):
    - PoC              (due: {sprint_6_end})    Sprints 1–6
    - Production Hardening (due: {sprint_12_end}) Sprints 7–12

Note: No "Phase" custom field — the milestone covers phase membership.

Proceed with onboarding? [Y/N]
```

**HALT HERE. Wait for user approval.**

### Step 5: Execute Setup

**Read `references/gh-commands.md` now** — you need the exact commands for every operation below.

If approved, execute in this order:

1. **Create or connect GitHub Project** (section 2) — if using existing, just get its node ID
2. **Create custom fields** (section 3) — Story ID, Epic, Sprint, Dev, Sprint Start, Sprint End, Story Points
3. **Query all field IDs** (section 4) — including the pre-existing Start date, Target date, Status fields
4. **Apply rainbow colors + sprint goal descriptions to Sprint and Epic fields** (section 13)
   - Sprint options: cycle RED→ORANGE→YELLOW→GREEN→BLUE→PURPLE→PINK, repeat
   - Sprint description = sprint objective from sprint-plan.md
   - Epic options: RED→ORANGE→YELLOW→GREEN→BLUE→PURPLE→PINK→RED→ORANGE→YELLOW→GREEN→BLUE
5. **Create labels** (section 5) — 17 labels total
6. **Create phase-based milestones** (section 6) — PoC and Production Hardening

> **Critical:** After calling `updateProjectV2Field` to set colors/descriptions, the single-select
> option IDs CHANGE (the mutation replaces the options list). Always re-query option IDs after
> calling this mutation and use the new IDs in the config.

### Step 6: Write Config

**Read `references/config-schema.md` now** — you need the exact YAML format.

Create `.github-sync.yaml` at project root with all populated IDs following that schema.
Note: No `phase` field in `field_ids` or `option_ids` — Phase was replaced by milestones.

### Step 7: Report Completion

```
Onboarding complete!
  Project: https://github.com/orgs/{owner}/projects/{number}
  Config: .github-sync.yaml

Next: Run "push stories to github" to create issues.
```

---

## Push Workflow (Files → GitHub)

Pushes BMAD story files to GitHub as issues, adds them to the project, sets all fields,
sets date fields, and establishes relationships.

### Step 1: Load Config

Rea