description: Publish a feature from /specs to GitHub Issues and Projects

Publish Feature to GitHub

This command publishes a feature from the /specs folder to GitHub, creating:

• An Epic issue containing the full requirements
• Phase issues for each phase in the implementation plan (with task checklists)
• A GitHub Project to track progress
• Labels for organization
• A github.md file in the specs folder with all references

Prerequisites

• The GitHub CLI (gh) must be authenticated: gh auth status
• The GitHub CLI must have project scopes: Token scopes should include project and read:project. If missing, run: gh auth refresh -s project,read:project
• A feature folder must exist in /specs with requirements.md and implementation-plan.md

Instructions

1. Identify the Feature

Look for the feature folder attached to the conversation or specified by the user.

The folder should be at /specs/{feature-name}/ and contain:

• requirements.md - Feature requirements
• implementation-plan.md - Task breakdown with phases

If no folder is specified, ask the user which feature to publish.

2. Extract Feature Information

• Feature name: Use the folder name (e.g., answer-scoring)
• Feature title: Parse the main heading from requirements.md
• Phases: Parse all phases from implementation-plan.md, including phase title, description, and task checklists

3. Get Repository Information

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

This returns both values, e.g., leonvanzyl/json-anything leonvanzyl

Store the results as:

• {repository} - Full repo name (e.g., leonvanzyl/json-anything)
• {owner} - Repository owner (e.g., leonvanzyl)

4. Create Labels (if they don't exist)

gh label create "epic" --color "7057ff" --description "Feature epic" 2>/dev/null || true
gh label create "feature/{feature-name}" --color "0E8A16" --description "Feature: {feature-title}" 2>/dev/null || true
gh label create "phase-1" --color "C5DEF5" --description "Phase 1 tasks" 2>/dev/null || true
gh label create "phase-2" --color "BFD4F2" --description "Phase 2 tasks" 2>/dev/null || true
gh label create "phase-3" --color "A2C4E0" --description "Phase 3 tasks" 2>/dev/null || true

5. Create the Epic Issue

Create an Epic issue with the full requirements:

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

Capture the issue number from the output (e.g., #100).

6. Create Phase Issues

For each phase in the implementation plan, create an issue containing all tasks for that phase:

Issue body template:

## Context

Part of Epic: #{epic-number}

## Overview

{Phase description/focus from implementation plan}

## Tasks

{Copy the full task checklist from the implementation plan for this phase, preserving markdown checkboxes}

## Technical Details

[Copy the full technical details section from the implementation plan for this phase]

## Acceptance Criteria

- [ ] All tasks in this phase completed
- [ ] Code passes lint and typecheck
- [ ] Changes follow project conventions

Command:

gh issue create \
  --title "Phase {n}: {Phase Title}" \
  --label "feature/{feature-name}" \
  --label "phase-{n}" \
  --body "{issue-body}"

Capture each phase issue number for linking.

6a. Handle Complex Phases (Optional)

If a phase meets any of these criteria, consider breaking out individual tasks as separate issues:

• Phase has more than 15 tasks
• A task has nested sub-tasks (indented checkboxes)
• A task is marked with [complex] in the implementation plan

For complex phases:

1. Create the phase issue as normal (it becomes the parent)
2. For each complex task, create a separate task issue:

gh issue create \
  --title "{Task description}" \
  --label "feature/{feature-name}" \
  --label "phase-{n}" \
  --body "## Context

Part of Phase: #{phase-issue-number}
Part of Epic: #{epic-number}

## Task

{Task description with any sub-tasks}

## Acceptance Criteria

- [ ] Implementation complete
- [ ] Code passes lint and typecheck
- [ ] Changes follow project conventions"

1. Update the phase issue to replace the task checkbox with a linked issue reference:

Before:

- [ ] Create complex authentication system [complex]

After:

- [ ] #{task-issue-number} Create complex authentication system

This way the phase issue still tracks all work, but complex tasks get their own issue for detailed discussion and tracking.

7. Update Epic with Phase List

Edit the Epic issue to include a list linking all phase issues:

gh issue edit {epic-number} --body "{original-body}

---

## Phases

- [ ] #{phase-1-number} Phase 1: {Phase 1 Title}
- [ ] #{phase-2-number} Phase 2: {Phase 2 Title}
- [ ] #{phase-3-number}