/sync-github

name: sync-github
description: Sync PRD with GitHub Issues (bidirectional)
category: Integration

Sync GitHub Command

Synchronize PRDs with GitHub Issues for team collaboration.

Purpose

Enable bidirectional sync between PRDs and GitHub Issues:

• Create GitHub Issues from PRDs
• Update PRD status when Issues close
• Link PRDs to Issues for easy access
• Enable team collaboration outside Claude Code

Usage

Create GitHub Issue from PRD

/sync-github PRD-003

Creates a GitHub Issue with:

• Title: "PRD-003: Feature Name"
• Body: Full PRD markdown
• Labels: Priority (P0/P1/P2) + "feature" + "PRD-003"
• Adds issue link to PRD metadata

Options

# Specify assignee
/sync-github PRD-003 --assignee=johndoe

# Add to milestone
/sync-github PRD-003 --milestone=v2.0

# Custom labels
/sync-github PRD-003 --labels=backend,api,urgent

# Skip confirmation
/sync-github PRD-003 --yes

Workflow

Step 1: Verify Prerequisites

Check that:

• GitHub CLI (`gh`) is installed and authenticated
• User is in a git repository
• PRD exists and is readable
• PRD not already synced (unless `--force`)

# Check gh auth
gh auth status

# If not authenticated, prompt user
gh auth login

Step 2: Read PRD Content

Load PRD file and extract metadata:

• PRD ID (e.g., PRD-003)
• Feature name
• Status
• Priority (P0/P1/P2/P3)
• Full markdown content

Step 3: Create GitHub Issue

Use GitHub CLI to create issue:

gh issue create \
  --title "PRD-003: Feature Name" \
  --body "$(cat prd_content.md)" \
  --label "P0,feature,PRD-003" \
  --assignee "johndoe" \
  --milestone "v2.0"

Step 4: Update PRD with Issue Link

Add to PRD metadata section (after Priority):

**Priority**: P0
**GitHub Issue**: #42 (https://github.com/org/repo/issues/42)
**Synced**: 2025-10-26

Step 5: Setup Bidirectional Sync (Optional)

Ask user if they want automatic status sync:

✅ GitHub Issue #42 created

🔗 Bidirectional sync available:
  • When issue closes → PRD moves to complete automatically
  • When PRD completes → Issue closes automatically

Enable? [Y/n]

If yes, add webhook handler (see below).

Bidirectional Sync Implementation

GitHub → PRD (Issue closes → Complete PRD)

Use GitHub CLI watch:

# In background (or via cron/systemd)
gh issue view 42 --json state -q .state

# When state changes to "CLOSED":
/complete-prd PRD-003

Better approach: GitHub Actions workflow

`.github/workflows/sync-prd-issue.yml`:

name: Sync PRD from Issue

on:
  issues:
    types: [closed, reopened]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Extract PRD ID from labels
        id: prd
        run: |
          LABELS=$(gh issue view ${{ github.event.issue.number }} --json labels -q '.labels[].name')
          PRD_ID=$(echo "$LABELS" | grep -o 'PRD-[0-9]\+')
          echo "prd_id=$PRD_ID" >> $GITHUB_OUTPUT

      - name: Complete PRD
        if: github.event.action == 'closed' && steps.prd.outputs.prd_id
        run: |
          # Find PRD file in 03-in-progress/
          PRD_FILE=$(find product/prds/03-in-progress -name "*${{ steps.prd.outputs.prd_id }}*")

          if [ -n "$PRD_FILE" ]; then
            # Move to 04-complete/
            mv "$PRD_FILE" product/prds/04-complete/

            # Commit
            git config user.name "github-actions[bot]"
            git config user.email "github-actions[bot]@users.noreply.github.com"
            git add .
            git commit -m "Complete ${{ steps.prd.outputs.prd_id }} (Issue #${{ github.event.issue.number }} closed)"
            git push
          fi

      - name: Reopen PRD
        if: github.event.action == 'reopened' && steps.prd.outputs.prd_id
        run: |
          # Move PRD back to 03-in-progress/
          PRD_FILE=$(find product/prds/04-complete -name "*${{ steps.prd.outputs.prd_id }}*")

          if [ -n "$PRD_FILE" ]; then
            mv "$PRD_FILE" product/prds/03-in-progress/
            git add .
            git commit -m "Reopen ${{ steps.prd.outputs.prd_id }} (Issue #${{ github.event.issue.number }} reopened)"
            git push
          fi

PRD → GitHub (Complete PRD → Close Issue)

Update `/complete-prd` command to close linked Issue:

# In /complete-prd workflow, after moving PRD to 04-complete/:

# Extract Issue number from PRD
ISSUE_NUMBER=$(grep "GitHub Issue.*#" "$PRD_FILE" | grep -o '#[0-9]\+' | tr -d '#')

if [ -n "$ISSUE_NUMBER" ]; then
  # Close issue
  gh issue close $ISSUE_NUMBER \
    --comment "✅ Completed via claude-prd-workflow" \
    --reason completed

  echo "Closed GitHub Issue #$ISSUE_NUMBER"
fi

Configuration

Add to plugin config (optional):

{
  "github": {
    "enabled": true,
    "auto_create_issue": false,
    "auto_sync_status": true,
    "default_labels": ["feature"],
    "sync_direction": "bidirectional"
  }
}

Error Handling

No GitHub CLI

❌ GitHub CLI (gh) not found

Install it:
  macOS: brew install gh
  Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
  Windows: winget install --id GitHub.cli

Then authenticate:
  gh auth login

Not Authenticated

❌ Not authenticated with GitHub

Run:
  gh auth login

And follow the prompts.

PRD Not Found

❌ PRD-999 not found

Available PRDs:
  - PRD-003 (in progress)
  - PRD-007 (ready)

Use:
  /list-prds

Already Synced

⚠️ PRD-003 already synced to GitHub Issue #42

Options:
  1. View issue: gh issue view 42 --web
  2. Update issue body: /sync-github PRD-003 --update
  3. Force create new: /sync-github PRD-003 --force

Continue? [y/N]

Success Criteria

• GitHub Issue created with correct title, body, labels
• Issue link added to PRD metadata
• User can view issue: `gh issue view 42 --web`
• Bidirectional sync works (if enabled)

Related Commands

• `/complete-prd` - Closes linked GitHub Issue
• `/list-