myclaude/docs/GITHUB-WORKFLOW.md

GitHub Workflow Commands

Issue-to-PR automation with codeagent-wrapper integration.

Overview

Two commands streamline GitHub workflows:

• /gh-create-issue - Create structured issues through guided dialogue
• /gh-implement - Implement issues with automated development lifecycle

Prerequisites

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

# Verify
gh auth status

Commands

/gh-create-issue

Create structured GitHub issues through multi-round dialogue.

Usage:

/gh-create-issue "add user authentication"

Process:

1. Initial Analysis - Claude analyzes your brief description
2. Clarification Questions - Interactive Q&A to gather:
   • Technical requirements
   • Acceptance criteria
   • Dependencies
   • Priority/labels
3. Issue Creation - Generates structured issue with:
   • Clear title
   • Detailed description
   • Acceptance criteria checklist
   • Relevant labels
   • Assignee (optional)

Example Session:

User: /gh-create-issue "add dark mode"

Claude: I'll help create a structured issue for dark mode. Let me gather some details.

1. Scope: Just theme toggle, or also persist user preference?
2. Which components need dark mode support?
3. Design system: Using CSS variables or styled-components?

User:
1. Toggle + persist in localStorage
2. All components in src/components
3. CSS variables

Claude: Creating issue...

✅ Issue created: #123 "Implement dark mode with theme persistence"
URL: https://github.com/user/repo/issues/123

Generated Issue Format:

# Implement dark mode with theme persistence

## Description
Add dark mode support across all components with user preference persistence.

## Requirements
- [ ] Add theme toggle component
- [ ] Implement CSS variables for light/dark themes
- [ ] Persist theme preference in localStorage
- [ ] Update all components in src/components to support dark mode
- [ ] Add theme toggle to app header

## Acceptance Criteria
- [ ] User can toggle between light and dark themes
- [ ] Theme preference persists across sessions
- [ ] All UI components render correctly in both themes
- [ ] No flash of unstyled content on page load

## Technical Notes
- Use CSS custom properties
- Store preference as `theme: 'light' | 'dark'` in localStorage
- Add `data-theme` attribute to root element

Labels: enhancement, ui

---

/gh-implement

Implement GitHub issue with full development lifecycle.

Usage:

/gh-implement 123

Phases:

Phase 1: Issue Analysis

# Fetches issue details
gh issue view 123 --json title,body,labels,comments

# Parses:
- Requirements
- Acceptance criteria
- Technical constraints
- Related discussions

Phase 2: Clarification (if needed)

Claude asks questions about:

• Implementation approach
• Architecture decisions
• Testing strategy
• Edge cases

Phase 3: Development

Option A: Simple scope - Direct codeagent-wrapper call:

codeagent-wrapper --backend codex - <<'EOF'
Implement dark mode toggle based on issue #123:
- Add ThemeToggle component
- Implement CSS variables
- Add localStorage persistence
EOF

Option B: Complex scope - Use /dev workflow:

/dev "implement issue #123: dark mode with theme persistence"

Coverage requirement: ≥90% test coverage enforced

Phase 4: Progress Updates

# After each milestone
gh issue comment 123 --body "✅ Completed: ThemeToggle component"
gh issue comment 123 --body "✅ Completed: CSS variables setup"
gh issue comment 123 --body "✅ Completed: localStorage persistence"

Phase 5: PR Creation

gh pr create \
  --title "[#123] Implement dark mode with theme persistence" \
  --body "Closes #123

## Changes
- Added ThemeToggle component
- Implemented light/dark CSS variables
- Added localStorage persistence
- Updated all components for theme support

## Testing
- Unit tests: ThemeToggle, theme utilities
- Integration tests: theme persistence across page loads
- Coverage: 92%"

Output:

✅ PR created: #124
URL: https://github.com/user/repo/pull/124

---

Examples

Example 1: Bug Fix

# Create issue
/gh-create-issue "login form doesn't validate email"

# Implement
/gh-implement 125

Process:

1. Analysis: Parse bug report, identify validation logic
2. Clarification: Confirm expected validation rules
3. Development: Fix validation, add tests
4. Updates: Comment with fix details
5. PR: Link to issue, show test coverage

---

Example 2: Feature Development

# Create issue
/gh-create-issue "add export to CSV feature"

# Implement
/gh-implement 126

Process:

1. Analysis: Understand data structure, export requirements
2. Clarification: Which data fields? File naming? Encoding?
3. Development:
   • Backend: CSV generation endpoint
   • Frontend: Export button + download handler
   • Tests: Unit + integration
4. Updates: Milestone comments (backend done, frontend done, tests done)
5. PR: Full feature description with screenshots

---

Example 3: Refactoring

# Create issue
/gh-create-issue "refactor authentication module"

# Implement
/gh-implement 127

Process:

1. Analysis: Review current auth code, identify issues
2. Clarification: Scope (just refactor vs add features)?
3. Development:
   • Modularize auth logic
   • Extract reusable utilities
   • Add missing tests
   • Update documentation
4. Updates: Component-by-component progress
5. PR: Before/after comparison, test coverage improvement

---

Workflow Integration

With /dev Workflow

# Create issue first
/gh-create-issue "implement real-time notifications"

# Then implement with /dev
/gh-implement 128

# Claude will:
# 1. Analyze issue #128
# 2. Trigger /dev workflow internally
# 3. Execute with 90% coverage requirement
# 4. Post progress updates
# 5. Create PR

With Parallel Tasks

For complex features, /gh-implement may use parallel execution:

# Internally executes:
codeagent-wrapper --parallel <<'EOF'
---TASK---
id: backend_notifications
workdir: /project/backend
---CONTENT---
implement notifications API with WebSocket

---TASK---
id: frontend_notifications
workdir: /project/frontend
dependencies: backend_notifications
---CONTENT---
build Notifications UI component

---TASK---
id: tests_notifications
workdir: /project
dependencies: backend_notifications, frontend_notifications
---CONTENT---
add E2E tests for notification flow
EOF

---

Configuration

Issue Templates

Create .github/ISSUE_TEMPLATE/feature.md:

---
name: Feature Request
about: Suggest a new feature
labels: enhancement
---

## Description
<!-- Clear description of the feature -->

## Requirements
<!-- Specific requirements -->

## Acceptance Criteria
<!-- Checklist of criteria -->

PR Templates

Create .github/PULL_REQUEST_TEMPLATE.md:

## Related Issue
Closes #

## Changes
<!-- List of changes -->

## Testing
<!-- Test coverage and manual testing -->

## Screenshots (if applicable)
<!-- Before/after screenshots -->

---

Best Practices

1. Clear issue descriptions - More context = better implementation
2. Incremental commits - Easier to review and rollback
3. Test-driven - Write tests before/during implementation
4. Milestone updates - Keep issue comments up-to-date
5. Detailed PRs - Explain why, not just what

---

Troubleshooting

Issue not found:

# Verify issue exists
gh issue view 123

# Check repository
gh repo view

PR creation failed:

# Ensure branch is pushed
git push -u origin feature-branch

# Check if PR already exists
gh pr list --head feature-branch

Authentication error:

# Re-authenticate
gh auth login

# Check token scopes
gh auth status

---

Advanced Usage

Custom Labels

# Add labels during issue creation
gh issue create \
  --title "Feature: dark mode" \
  --body "..." \
  --label "enhancement,ui,priority:high"

Multiple Assignees

# Assign to team members
gh issue create \
  --title "..." \
  --assignee @user1,@user2

Milestone Assignment

# Add to milestone
gh issue create \
  --title "..." \
  --milestone "v2.0"

---

Integration with CI/CD

Auto-close on merge

# .github/workflows/pr-merge.yml
name: Close Issues on PR Merge
on:
  pull_request:
    types: [closed]

jobs:
  close-issues:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - name: Close linked issues
        run: gh issue close ${{ github.event.pull_request.number }}

Coverage Check

# .github/workflows/coverage.yml
name: Coverage Check
on: [pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests with coverage
        run: go test -coverprofile=coverage.out ./...
      - name: Check coverage threshold
        run: |
          coverage=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')
          if (( $(echo "$coverage < 90" | bc -l) )); then
            echo "Coverage $coverage% is below 90% threshold"
            exit 1
          fi

---

Further Reading

• GitHub CLI Manual
• Codeagent-Wrapper Guide
• Hooks Documentation
• Development Workflow