publish-to-github

Publish Feature to GitHub

Publish a feature from /specs folder to GitHub with full Project Roadmap support.

Prerequisites

• GitHub CLI (gh) authenticated: gh auth status
• Project scope required: gh auth refresh -s project,read:project
• Feature folder in /specs with requirements.md and implementation-plan.md

Execution Checklist

Execute ALL steps in order. DO NOT skip any step.

1. Locate Feature Folder

• Find /specs/{feature-name}/ folder
• Verify requirements.md exists
• Verify implementation-plan.md exists

2. Extract Information

• Feature name: use folder name
• Feature title: main heading from requirements.md
• Phase list: parse from implementation-plan.md (including estimated duration if specified)

3. Get Repository Info

gh repo view --json nameWithOwner,owner -q '.nameWithOwner + " " + .owner.login'

4. Create Labels (REQUIRED)

gh label create "epic" --color "7057ff" --description "Feature epic" 2>/dev/null || true
gh label create "feature/{feature-name}" --color "0E8A16" --description "Feature: {title}" 2>/dev/null || true
gh label create "phase-1" --color "C5DEF5" --description "Phase 1" 2>/dev/null || true
gh label create "phase-2" --color "C5DEF5" --description "Phase 2" 2>/dev/null || true
# Repeat for each phase

5. Create Milestone (REQUIRED - for Roadmap grouping)

gh api repos/{owner}/{repo}/milestones --method POST \
  -f title="Feature: {Feature Title}" \
  -f description="{Feature description from requirements.md}" \
  -f due_on="{target-completion-date-ISO8601}"

• Save Milestone number

6. Create Epic Issue (REQUIRED)

gh issue create \
  --title "Epic: {Feature Title}" \
  --label "epic" \
  --label "feature/{feature-name}" \
  --milestone "Feature: {Feature Title}" \
  --body-file specs/{feature-name}/requirements.md

• Save Epic issue number

7. Create Phase Issues (REQUIRED)

For each Phase:

gh issue create \
  --title "Phase {N}: {Phase Title}" \
  --label "feature/{feature-name}" \
  --label "phase-{N}" \
  --milestone "Feature: {Feature Title}" \
  --body "## Tasks\n\n{checklist}\n\n## Technical Details\n\n{details from implementation-plan}"

• Save all Phase issue numbers

8. Update Epic (REQUIRED)

Add Phase issue links to Epic:

gh issue edit {epic-number} --body "{existing content}\n\n## Phase Issues\n- #{phase1}\n- #{phase2}"

9. Create GitHub Project (REQUIRED - MUST EXECUTE)

# Create Project
gh project create --title "Feature: {Feature Title}" --owner {owner} --format json

• Save Project number (from JSON output)

# Link to repository
gh project link {project-number} --owner {owner} --repo {repo-name}

10. Setup Project Fields for Roadmap (REQUIRED - MUST EXECUTE)

Get existing fields:

gh project field-list {project-number} --owner {owner} --format json

Create date fields if not exist:

# Create Start Date field
gh project field-create {project-number} --owner {owner} --name "Start Date" --data-type DATE

# Create End Date field
gh project field-create {project-number} --owner {owner} --name "End Date" --data-type DATE

# Create Phase field (Single Select for grouping)
gh project field-create {project-number} --owner {owner} --name "Phase" --data-type SINGLE_SELECT \
  --single-select-options "Phase 1,Phase 2,Phase 3,Phase 4,Phase 5"

• Save field IDs (Start Date, End Date, Phase, Status)

11. Add Issues to Project with Roadmap Data (REQUIRED - MUST EXECUTE)

For Epic:

# Add to project
gh project item-add {project-number} --owner {owner} --url "https://github.com/{owner}/{repo}/issues/{epic-number}"

# Get item ID
ITEM_ID=$(gh project item-list {project-number} --owner {owner} --format json | jq -r '.items[] | select(.content.number == {epic-number}) | .id')

# Set dates (Epic spans entire feature timeline)
gh project item-edit --project-id {project-id} --id $ITEM_ID --field-id {start-date-field-id} --date "{start-date-YYYY-MM-DD}"
gh project item-edit --project-id {project-id} --id $ITEM_ID --field-id {end-date-field-id} --date "{end-date-YYYY-MM-DD}"

For each Phase issue:

# Add to project
gh project item-add {project-number} --owner {owner} --url "https://github.com/{owner}/{repo}/issues/{phase-number}"

# Get item ID
ITEM_ID=$(gh project item-list {project-number} --owner {owner} --format json | jq -r '.items[] | select(.content.number == {phase-number}) | .id')

# Set Phase group
gh project item-edit --project-id {project-id} --id $ITEM_ID --field-id {phase-field-id} --single-select-option-id {phase-N-option-id}

# Set dates for this phase
gh project item-edit --project-id {project-id} --id $ITEM_ID --field-id {start-date-field-id} --date "{phase-start-YYYY-MM-DD}"
gh project item-edit --project-id {project-id} --id $ITEM_ID --field-id {end-date-field-id} --date "{phase-end-YYYY-MM-DD}"

# Set initial status to "Todo"
gh project item-edit --project-id {project-id} --id $ITEM_ID --field-id {status-field-id} --single-select-option-id {todo-option-id}

Date Estimation Logic:

• If implementation-plan.md has duration estimates, use them
• Otherwise, estimate 1-2 days per task, phases sequential
• Start date: today for Phase 1, end of previous phase for others
• End date: start + estimated duration

12. Create Roadmap View (REQUIRED - MUST EXECUTE)

Note: Roadmap view must be created via GitHub web UI or API. Document the setup:

# Add comment to Epic with Roadmap setup instructions
gh issue comment {epic-number} --body "## Project Roadmap

View the roadmap at: https://github.com/users/{owner}/projects/{project-number}/views/1

### Roadmap View Setup (if not visible)
1. Go to Project → Add View → Roadmap
2. Set Date field to 'Start Date'
3. Set Target date field to 'End Date'
4. Group by 'Phase' field
5. Show Milestones"

13. Create github.md (REQUIRED - MUST EXECUTE)

You MUST create specs/{feature-name}/github.md:

---
feature_name: {feature-name}
repository: {owner}/{repo}
epic_issue: {epic-number}
milestone: {milestone-number}
project_number: {project-number}
project_id: {project-id}
created_at: {YYYY-MM-DD}
fields:
  status: {status-field-id}
  start_date: {start-date-field-id}
  end_date: {end-date-field-id}
  phase: {phase-field-id}
---

# GitHub References: {Feature Title}

## Issues

- Epic: #{epic-number}
- Phase 1: #{phase1-number} (Start: {date}, End: {date})
- Phase 2: #{phase2-number} (Start: {date}, End: {date})
...

## Project

- Board: https://github.com/users/{owner}/projects/{project-number}
- Roadmap: https://github.com/users/{owner}/projects/{project-number}/views/1

## Milestone

- {milestone-name}: https://github.com/{owner}/{repo}/milestone/{milestone-number}

## Labels

- `epic`
- `feature/{feature-name}`
- `phase-1`, `phase-2`, ...

## Field IDs (for automation)

- Status: {status-field-id}
- Start Date: {start-date-field-id}
- End Date: {end-date-field-id}
- Phase: {phase-field-id}

14. Report Results (REQUIRED)

You MUST output the following:

GitHub Publish Complete

Epic: https://github.com/{owner}/{repo}/issues/{epic-number}
Milestone: https://github.com/{owner}/{repo}/milestone/{milestone-number}
Phase Issues: {N} created
Total Tasks: {M}
Project Board: https://github.com/users/{owner}/projects/{project-number}
Project Roadmap: https://github.com/users/{owner}/projects/{project-number}/views/1
github.md: specs/{feature-name}/github.md created

Roadmap Features:
- Start/End dates set for all phases
- Phase grouping enabled
- Milestone tracking active

Error Handling

Error	Solution
gh auth failed	Guide to run gh auth login
project scope missing	Guide to run gh auth refresh -s project,read:project
Feature folder missing	Guide to run /create-spec first
github.md already exists	Ask to overwrite
field-create fails	Field may already exist, get existing field ID

IMPORTANT

• Steps 9, 10, 11, 12, 13 MUST be executed
• Without github.md, /continue-feature will NOT work
• Without Project, progress tracking is impossible
• Date fields enable Roadmap view visualization
• Phase field enables grouping in Roadmap
• Milestone enables progress tracking and due dates