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

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.

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

• .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.

references/gh-commands.md

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.

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

• H1 is plain

  # Story X.X: Title

  (no link) → CREATE
• H1 contains

  # [Story X.X: Title](url)

  → UPDATE (already synced)

1. Read the file using the Read tool
2. Read

   references/content-mapping.md

   — sections 1–4 and 9 for the exact format
3. Build the issue body following the template:
   • User story blockquote
   • AC as one-line Then-clause summaries (checkboxes)
   • Full task list (Task 2+ only — exclude agent-only tasks by reading content, not by position)
   • Dependencies with

     #N

     GitHub issue numbers
   • Collapsible dev notes: tables, config snippets, architecture patterns — NOT code skeletons, NOT ASCII trees, NOT "What NOT to Do" lists, NOT references
4. Look up sprint/dev/epic from sprint-plan.md (NOT from the story file body)

1. Write issue body to a temp file (

   /tmp/issue-{story_id}.md

   )

2. gh issue create --title "..." --body-file /tmp/... --label "epic:X-name" --label "phase:poc" --milestone "{PoC|Production Hardening}"

3. Extract issue URL from output

4. gh project item-add {project_number} --owner {owner} --url {issue_url} --format json

5. Extract item ID from JSON output
6. Set all project fields using

   gh project item-edit

   :
   • Story ID (text)
   • Epic (single-select option)
   • Sprint (single-select option, e.g., "Sprint 01")
   • Dev (single-select option)
   • Sprint Start (date from sprint-plan.md)
   • Sprint End (date from sprint-plan.md)
   • Status (Backlog)
   • Start date (same date as Sprint Start — pre-existing field)
   • Target date (same date as Sprint End — pre-existing field)
7. Write link-back to local file: replace H1 with

   # [Story X.X: Title](issue_url)

1. Write updated body to temp file

2. gh issue edit {number} --body-file /tmp/... --milestone "{phase_milestone}"

3. Update project fields if sprint/epic changed

sprint-plan.md

Dependencies

A → B

mutation {
  addBlockedBy(input: {
    issueId: "{story_A_node_id}"
    blockingIssueId: "{story_B_node_id}"
  }) {
    issue { number }
    blockingIssue { number }
  }
}

Always source dependencies from sprint-plan.md, not from story file bodies. The sprint plan is the authoritative dependency record.

gh api graphql -f query='
  query {
    repository(owner:"{owner}", name:"{repo}") {
      issues(first:50, orderBy:{field:CREATED_AT, direction:ASC}) {
        nodes { number id title }
      }
    }
  }
'

1. Find the matching local story file (by story ID → filename pattern)
2. Compare GitHub state with local file state:
   • Status: GitHub status vs local

     Status:

     line
   • Assignee: GitHub assignee vs local dev mapping
   • Task checkboxes: GitHub issue body checkboxes vs local file checkboxes

1. Read the story file
2. Update the

   Status:

   line with the mapped BMAD status
3. Write the file back
4. Update config

   last_synced