github-planning

What this skill does

# GitHub Planning

Create GitHub Issues and Projects instead of local markdown files for planning artifacts.

## Modern GitHub Features (2024+)

This skill leverages modern GitHub capabilities:

| Feature | Description | When Used |
|---------|-------------|-----------|
| Native Sub-Issues | GitHub's built-in parent/child relationship | STANDARD, COMPLEX |
| YAML Issue Forms | Structured input templates | All tiers |
| Projects v2 API | GraphQL-based project management | COMPLEX |
| Milestones | Time-boxed release tracking | STANDARD, COMPLEX |
| Label Taxonomy | Structured labeling (type:*, priority:*, status:*) | All tiers |

## Contextd Integration (Optional)

If contextd MCP is available:
- `memory_record` for planning decisions

If contextd is NOT available:
- GitHub artifact creation works normally
- No cross-session memory of planning decisions

## When to Use

Called by `/brainstorm` Phase 6 after design is complete to create:
- **SIMPLE:** Single Issue with checklist
- **STANDARD:** Epic Issue + native sub-Issues + Milestone
- **COMPLEX:** Epic + native sub-Issues + Projects v2 board + Automation

## Prerequisites

- `gh` CLI authenticated (`gh auth status`)
- Repository has GitHub remote configured
- Complexity tier determined (from complexity-assessment)
- For Projects v2: GitHub GraphQL API access (`gh api graphql`)

---

## Label Taxonomy (Required)

**Create these labels in your repository if they don't exist:**

### Type Labels
```bash
gh label create "type:epic" --color "8B5CF6" --description "Epic/parent issue"
gh label create "type:feature" --color "10B981" --description "New feature"
gh label create "type:bug" --color "EF4444" --description "Bug report"
gh label create "type:task" --color "3B82F6" --description "Implementation task"
gh label create "type:chore" --color "6B7280" --description "Maintenance/housekeeping"
gh label create "type:docs" --color "F59E0B" --description "Documentation"
```

### Priority Labels
```bash
gh label create "priority:critical" --color "DC2626" --description "P0 - Drop everything"
gh label create "priority:high" --color "F97316" --description "P1 - This sprint"
gh label create "priority:medium" --color "EAB308" --description "P2 - Next sprint"
gh label create "priority:low" --color "84CC16" --description "P3 - Backlog"
```

### Status Labels
```bash
gh label create "status:blocked" --color "FEE2E2" --description "Blocked by dependency"
gh label create "status:needs-review" --color "DBEAFE" --description "Ready for review"
gh label create "status:in-progress" --color "FEF3C7" --description "Currently being worked"
```

---

## Tier-Based Output

### SIMPLE Tier

Create single Issue with checkbox checklist:

```bash
gh issue create \
  --title "<feature-name>" \
  --label "type:task,priority:medium" \
  --body "$(cat <<'EOF'
## Overview
<1-2 sentence description>

## Tasks
- [ ] <task 1>
- [ ] <task 2>
- [ ] <task 3>

## Verification
| Type | Details | Expected |
|------|---------|----------|
| <type> | <command/steps> | <expected outcome> |

## Definition of Done
- [ ] All tasks checked off
- [ ] Verification criteria pass
- [ ] No regressions introduced

## Context
- Complexity: SIMPLE
- Created by: /brainstorm
EOF
)"
```

### STANDARD Tier

Create Epic Issue + native sub-Issues + Milestone:

**1. Create Milestone (if needed):**
```bash
gh api repos/{owner}/{repo}/milestones \
  --method POST \
  -f title="<milestone-name>" \
  -f description="<milestone-description>" \
  -f due_on="<YYYY-MM-DDTHH:MM:SSZ>"
```

**2. Create Epic:**
```bash
gh issue create \
  --title "[EPIC] <feature-name>" \
  --label "type:epic,priority:high" \
  --milestone "<milestone-name>" \
  --body "$(cat <<'EOF'
## Overview
<description>

## Sub-Issues
<!-- Native sub-issues will be linked automatically -->

## Success Criteria
<what done looks like>

## Definition of Done
- [ ] All sub-issues closed
- [ ] Integration tests pass
- [ ] Documentation updated
- [ ] No P0/P1 bugs outstanding

## Context
- Complexity: STANDARD
- Created by: /brainstorm
EOF
)"
```

**3. Create Native Sub-Issues (GitHub 2024+ feature):**
```bash
# Get Epic node ID first
EPIC_ID=$(gh api graphql -f query='
  query($owner: String!, $repo: String!, $number: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $number) {
        id
      }
    }
  }
' -f owner="<owner>" -f repo="<repo>" -F number=<epic-number> --jq '.data.repository.issue.id')

# Create sub-issue with native parent relationship
gh api graphql -f query='
  mutation($repositoryId: ID!, $title: String!, $body: String!, $parentId: ID!) {
    createIssue(input: {
      repositoryId: $repositoryId
      title: $title
      body: $body
      parentIssueId: $parentId
    }) {
      issue {
        number
        url
      }
    }
  }
' -f repositoryId="<repo-id>" \
  -f title="<task-name>" \
  -f body="<task-body>" \
  -f parentId="$EPIC_ID"
```

**Alternative: REST API for sub-issues (if GraphQL unavailable):**
```bash
gh issue create \
  --title "<task-name>" \
  --label "type:task" \
  --milestone "<milestone-name>" \
  --body "$(cat <<'EOF'
## Description
<task description>

## Verification
| Type | Details | Expected |
|------|---------|----------|
| <type> | <command/steps> | <expected outcome> |

## Definition of Done
- [ ] Implementation complete
- [ ] Tests written and passing
- [ ] Verification criteria met

## Parent
Contributes to #<epic-number>
EOF
)"

# Then link via API:
gh api repos/{owner}/{repo}/issues/<sub-issue>/sub_issues \
  --method POST \
  -f parent_issue_id=<epic-id>
```

### COMPLEX Tier

Create Epic + native sub-Issues + Projects v2 board with automation:

**1. Create Epic and Sub-Issues** (same as STANDARD)

**2. Create Projects v2 board with GraphQL:**
```bash
# Get owner ID
OWNER_ID=$(gh api graphql -f query='
  query($login: String!) {
    user(login: $login) { id }
  }
' -f login="<owner>" --jq '.data.user.id')

# Create Project v2
PROJECT_ID=$(gh api graphql -f query='
  mutation($ownerId: ID!, $title: String!) {
    createProjectV2(input: {
      ownerId: $ownerId
      title: $title
    }) {
      projectV2 {
        id
        number
      }
    }
  }
' -f ownerId="$OWNER_ID" -f title="<feature-name>" --jq '.data.createProjectV2.projectV2.id')
```

**3. Configure Projects v2 Fields:**
```bash
# Add Status field (single select)
gh api graphql -f query='
  mutation($projectId: ID!, $name: String!) {
    createProjectV2Field(input: {
      projectId: $projectId
      dataType: SINGLE_SELECT
      name: $name
      singleSelectOptions: [
        {name: "Backlog", color: GRAY}
        {name: "Ready", color: BLUE}
        {name: "In Progress", color: YELLOW}
        {name: "In Review", color: PURPLE}
        {name: "Done", color: GREEN}
      ]
    }) {
      projectV2Field { id }
    }
  }
' -f projectId="$PROJECT_ID" -f name="Status"

# Add Priority field
gh api graphql -f query='
  mutation($projectId: ID!, $name: String!) {
    createProjectV2Field(input: {
      projectId: $projectId
      dataType: SINGLE_SELECT
      name: $name
      singleSelectOptions: [
        {name: "P0 Critical", color: RED}
        {name: "P1 High", color: ORANGE}
        {name: "P2 Medium", color: YELLOW}
        {name: "P3 Low", color: GREEN}
      ]
    }) {
      projectV2Field { id }
    }
  }
' -f projectId="$PROJECT_ID" -f name="Priority"

# Add Sprint/Iteration field
gh api graphql -f query='
  mutation($projectId: ID!, $name: String!) {
    createProjectV2Field(input: {
      projectId: $projectId
      dataType: ITERATION
      name: $name
    }) {
      projectV2Field { id }
    }
  }
' -f projectId="$PROJECT_ID" -f name="Sprint"
```

**4. Create Project Views:**
```bash
# Create Board View
gh api graphql -f query='
  mutation($projectId: ID!, $name: String!) {
    createProjectV2View(input: {
      projectId: $projectId
      name: $name
      layout: BOARD_LAYOUT
    }) {
      projectV2View { id }
    }
  }
' -f projectId="$PROJECT_ID" -f name="B