github-sync

Files (6)

• SKILL.md
• evals.json · evals/
• config-schema.md · references/
• content-mapping.md · references/
• gh-commands.md · references/
• parse-artifacts.py · scripts/

SKILL.md (first lines)

# 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

From bmad-labs/skills, MIT.

More from bmad-labs/skills