Github Issues Setup

GitHub Issues Setup -- Standard Project Initialization

Sets up the standard evergreen issues + labels for a DazzleTools/djdarcy project.

Canonical convention: this skill is the single source of truth for standalone issue setup and mirrors create-project Phase 8 -- keep the two in sync. It supersedes the retired setup-github-project command (consolidated 2026-06-19).

What This Does

1. Creates the standard label set (pinned, evergreen, roadmap, scratchpad, architecture, epic, ideas, CurrentTask, NextTask)
2. Creates Issue #1: Roadmap (evergreen, never closes)
3. Creates Issue #2: Quick Notes -- Bugs, Features, Ideas (evergreen, never closes)
4. Stores issue body files in private/claude/issues/ for future reference

Prerequisites

• gh CLI authenticated
• A GitHub repo already exists for the project
• Working directory is the project root (with .git/)

Process

Step 1: Create Labels

Check existing labels first (gh label list) to avoid duplicates, then:

gh label create "pinned"       --color "d4c5f9" --description "Permanently open issue"
gh label create "evergreen"    --color "2ea44f" --description "Never close -- living document updated over time"
gh label create "roadmap"      --color "0075ca" --description "Project roadmap"
gh label create "scratchpad"   --color "f9d0c4" --description "Quick notes and scratch space"
gh label create "architecture" --color "bfd4f2" --description "Structural decisions"
gh label create "epic"         --color "5319e7" --description "Large multi-phase initiative"
gh label create "ideas"        --color "c5def5" --description "Exploratory ideas"
gh label create "CurrentTask"  --color "0e8a16" --description "Currently being worked on"
gh label create "NextTask"     --color "e6b800" --description "Next item to pick up"

Step 2: Draft Issue Bodies

Do NOT hard-wrap the body prose. Issue bodies render on GitHub and reflow on their own — write one line per paragraph. Hard-wrapping at ~80 cols makes the issue painful to edit and can mis-render in lists. (Fix after the fact with dz md-unwrap -i.)

Create private/claude/issues/ directory. Draft two files:

issue_roadmap.md structure:

## Roadmap

Evergreen tracking issue for [ProjectName] development priorities.

### Phase 1: Foundation
- [x] Completed items
- [ ] Pending items (#N)

### Phase 2: Core Features
- [ ] Items...

### Phase 3: Refactor / Modernization
- [ ] Items...

### Phase 4: Advanced / Future
- [ ] Items...

issue_notes_ideas.md structure:

## Quick Notes -- Bugs, Features, Ideas

Evergreen scratch space for [ProjectName]: small bugs, feature seeds, and ideas
that don't warrant their own issue yet. Items get promoted to proper issues when
they mature.

### Bugs
- (none yet)

### Features
- Bullet feature seeds...

### Ideas / Research
- Exploratory ideas...

### Architecture Notes
- Decisions, gotchas, observations...

### Recently Completed
- (rolling log)

Customize the content for the specific project. The phase structure and section headings are flexible -- adapt to the project's actual scope.

Step 3: Create Issues

CRITICAL: Issues must be #1 and #2. If the repo already has issues, coordinate first (gh issue list --state all --limit 5).

gh issue create --title "Roadmap" --label "pinned,roadmap,evergreen" \
  --body-file private/claude/issues/issue_roadmap.md

gh issue create --title "Quick Notes -- Bugs, Features, Ideas" --label "pinned,scratchpad,evergreen" \
  --body-file private/claude/issues/issue_notes_ideas.md

Step 4: Actually pin the issues (not just the label)

The pinned LABEL is cosmetic -- GitHub's real "pin" feature (up to 3 issues at the top of the Issues tab) is a separate GraphQL mutation with no gh issue pin command, so it is easy to forget. Pin both evergreen issues. Resolve numbers by title, not by assuming #1/#2 -- a Dependabot PR often takes #1, shifting the issues to #2/#3.

for TITLE in "Roadmap" "Quick Notes"; do
  NUM=$(gh issue list --state open --search "$TITLE in:title" \
        --json number,title --jq "map(select(.title|startswith(\"$TITLE\")))[0].number")
  ID=$(gh issue view "$NUM" --json id --jq '.id')
  gh api graphql -f query="mutation { pinIssue(input: {issueId: \"$ID\"}) { issue { number } } }"
done

Step 5: Verify

gh issue list --label pinned
gh api graphql -f query='{ repository(owner: "OWNER", name: "REPO") { pinnedIssues(first: 5) { nodes { issue { number title } } } } }'

Both issues should show as OPEN with the pinned label AND appear in pinnedIssues (actually pinned on the repo).

User Input Required

• $ARGUMENTS: Optional project description or context to customize the roadmap phases and notes content. If empty, ask the user what the project is about and what work has been done / is planned.

Reference

• Canonical convention: mirrors create-project Phase 8; keep them in sync.
• Format examples: djdarcy/github-traffic-tracker#1 (Roadmap), #2 (Quick Notes)
• The pinned (#d4c5f9) + evergreen (#2ea44f) labels mark living issues that never close
• Issue body files stored at private/claude/issues/ (gitignored via repokit)
• Supersedes the retired setup-github-project command (consolidated 2026-06-19)