GitHub Integration — Detailed Steps and Examples

GitHub Integration — Detailed Steps and Examples

Step 2.5: GitHub Issue Sync

After extracting item fields (Step 2), check for an existing linked issue:

1. Search the matched item for **Issue**: #N field.

2. If found: issue already linked. Run:

   gh issue view N -R Jamie-BitFlight/claude_skills --json number,title,state,labels
   

   Report the issue state. If open, proceed. If closed, warn the user before re-opening planning.

3. If not found AND priority is P0 or P1: offer to create a GitHub Issue:

   This P1 item has no linked GitHub issue. Create one? (yes/no)
   

   If yes, proceed to 2.5a. If no, skip GitHub sync; BACKLOG.md remains the only record.

4. If not found AND priority is P2 or Ideas: do not prompt; skip GitHub sync silently.

Step 2.5a: Create GitHub Issue

Invoke the backlog script:

uv run .claude/skills/backlog/scripts/backlog.py update "{title}" --create-issue -R Jamie-BitFlight/claude_skills

The script creates the issue and writes **Issue**: #N back to BACKLOG.md.

Step 2.7: Set In-Progress Label

Invoke the backlog script:

uv run .claude/skills/backlog/scripts/backlog.py update "{title}" --status in-progress -R Jamie-BitFlight/claude_skills

If the item is in a milestone with other issues, also run milestone start:

uv run .claude/skills/gh/scripts/github_project_setup.py milestone start \
  --number {milestone_number} --repo Jamie-BitFlight/claude_skills

Step 9: Close — backlog script

Invoke the backlog script (replaces direct BACKLOG write + gh issue close):

uv run .claude/skills/backlog/scripts/backlog.py close "{title}" --plan "{plan path}" --checklist-pass -R Jamie-BitFlight/claude_skills

The script writes the closing record to BACKLOG.md and closes the GitHub issue.

setup-github Command

Trigger: $ARGUMENTS is exactly setup-github.

1. Run label taxonomy setup:

   uv run .claude/skills/gh/scripts/github_project_setup.py labels \
     --repo Jamie-BitFlight/claude_skills
   

2. Check for existing milestones:

   gh api repos/Jamie-BitFlight/claude_skills/milestones
   

   If none exist, create the first milestone:

   gh api repos/Jamie-BitFlight/claude_skills/milestones \
     -X POST \
     -f title="v1.0 — Skills Foundation" \
     -f description="Initial stable milestone for claude_skills skills and plugins" \
     -f due_on="2026-03-31T00:00:00Z"
   

3. Check for existing projects:

   gh project list --owner Jamie-BitFlight
   

   If none exist, prompt: "Create GitHub Project 'claude_skills Backlog'? (yes/no)" If yes:

   gh project create --owner Jamie-BitFlight --title "claude_skills Backlog"
   gh project link 1 --owner Jamie-BitFlight --repo Jamie-BitFlight/claude_skills
   

4. Report setup summary:

   GitHub setup complete:
   - Labels: N created
   - Milestone: #1 "v1.0 — Skills Foundation"
   - Project: #1 "claude_skills Backlog" (linked to repo)
   
   Next steps:
   - Add custom fields: .claude/skills/gh/references/projects-v2.md
   - Import existing backlog: /work-backlog-item <title> for each P0/P1 item
   

Example Sessions

GitHub Issue Creation Flow

> /work-backlog-item clang-format YAML frontmatter

Found: "clang-format: Fix broken YAML frontmatter" (P1)
No grooming manifest. Running groom-backlog-item first...

RT-ICA: APPROVED
This P1 item has no linked GitHub issue. Create one? yes

Creating issue...
  Title: fix: correct YAML frontmatter in clang-format SKILL.md
  Labels: priority:p1, type:bug, status:needs-grooming

Created: #59 — https://github.com/Jamie-BitFlight/claude_skills/issues/59
Updated BACKLOG.md: **Issue**: #59

Setting status:in-progress...
  ✓ Added status:in-progress, removed status:needs-grooming

Composing feature request...
Invoking /python3-development:add-new-feature...

[SAM phases run]

Updated BACKLOG.md with Plan: plan/tasks-3-clang-format-yaml.md
GitHub issue #59 — Plan added to issue body.

Next steps:
- To execute:      /python3-development:implement-feature clang-format-yaml
- To close when done: /work-backlog-item close clang-format

GitHub Setup Session

> /work-backlog-item setup-github

Setting up GitHub project infrastructure...

1. Creating label taxonomy...
   created: priority:p0, priority:p1, priority:p2, priority:idea
   created: type:feature, type:bug, type:refactor, type:docs, type:chore
   created: status:in-progress, status:blocked, status:needs-grooming, status:needs-review
   Labels: 13 created, 0 skipped

2. Creating milestone: v1.0 — Skills Foundation
   Created milestone #1

3. Create GitHub Project 'claude_skills Backlog'? yes
   Created project #1, linked to repo

GitHub setup complete.

Field Mapping Reference

BACKLOG.md          →  GitHub Issue
  Priority section  →  priority:* label
  Description       →  Issue body (story format)
  Status            →  status:* label
  Plan file         →  Issue body Notes
  **Issue**: #N     ←  written back after creation
  Completed         →  Issue closed

See issue-stories.md for the full body template and lifecycle.