Skip to content

README.md

Latest commit

 

History

History
211 lines (152 loc) · 5.08 KB

README.md

File metadata and controls

211 lines (152 loc) · 5.08 KB
Raw

sc-github-issue

GitHub issue lifecycle management with worktree isolation for Claude Code.

Overview

sc-github-issue provides a complete workflow for managing GitHub issues - from listing and creating issues to implementing fixes in isolated worktrees and creating pull requests. It integrates with sc-git-worktree to ensure fixes are implemented safely without affecting your main working directory.

Features

  • List Issues: Browse open/closed issues with filtering
  • Create/Update Issues: Interactive issue management
  • Fix Workflow: Automated fix implementation with:
    • Isolated worktree creation
    • Code analysis and implementation
    • Automated testing
    • Commit and push automation
    • Pull request creation with auto-linking
  • Safety Gates: Approval prompts and pre-flight checks
  • Template Support: Customizable PR templates

Installation

Prerequisites

  • Claude Code CLI
  • GitHub CLI (gh) version 2.0 or higher
  • sc-git-worktree package (auto-installed as dependency)

Install Package

sc-manage install sc-github-issue

This installs locally to your project (.claude/packages/sc-github-issue/).

Usage

List Issues

/sc-github-issue --list
/sc-github-issue --list --repo owner/repo

Create Issue

/sc-github-issue --create

Prompts for title, body, labels, and assignees.

Update Issue

/sc-github-issue --update 42

Fix Issue (Full Workflow)

/sc-github-issue --fix --issue 42
/sc-github-issue --fix --issue https://github.com/owner/repo/issues/42
/sc-github-issue --fix --issue 42 --yolo  # Skip confirmation prompts

Workflow steps:

  1. Fetches issue details and displays summary
  2. Prompts for confirmation (unless --yolo)
  3. Creates isolated worktree (fix-issue-42)
  4. Implements fix, runs tests, commits
  5. Pushes changes to remote
  6. Creates pull request with auto-linking
  7. Displays summary and PR URL

Configuration

Configuration via manifest options (defaults shown):

packages:
  sc-github-issue:
    base-branch: "main"              # Base branch for fix branches
    branch-pattern: "fix-issue-{number}"  # Branch naming pattern
    auto-pr: true                    # Auto-create PR after fix

Additional GitHub settings:

github:
  test_command: "npm test"           # Optional: Command to run tests
  pr_template: |                     # Optional: PR body template
    ## Summary
    Fixes #{issue_number}

    ## Changes
    {commits}

Architecture

Agents

  • sc-github-issue-intake: Read-only operations (list, fetch)
  • sc-github-issue-mutate: Write operations (create, update)
  • sc-github-issue-fix: Implement fixes in isolated worktrees
  • sc-github-issue-pr: Create pull requests with auto-linking

Dependencies

  • sc-git-worktree >= 0.6.0: Worktree isolation
  • gh >= 2.0: GitHub CLI for all operations

Why Worktree Isolation?

The --fix workflow uses sc-git-worktree to create isolated worktrees:

Benefits:

  • Main working directory remains clean
  • No need to stash changes
  • Safe parallel development
  • Branch-specific environment

Example:

main/                    # Your main working directory (untouched)
worktrees/
  └── fix-issue-42/     # Isolated fix environment

After PR is merged, clean up with:

/sc-git-worktree --cleanup --worktree fix-issue-42

Examples

Fix Bug Report

# List bugs
/sc-github-issue --list

# Fix issue #42
/sc-github-issue --fix --issue 42

# Output:
# ✓ Issue #42: Application crashes on startup
# ✓ Worktree created: fix-issue-42
# ✓ Fix implemented
# ✓ Tests passed (15/15)
# ✓ Committed: abc123def
# ✓ PR created: https://github.com/owner/repo/pull/123

Automated Workflow (CI/CD)

# Skip confirmation prompts
/sc-github-issue --fix --issue $ISSUE_NUMBER --yolo

Security

  • Pre-flight checks: Validates gh auth, repo access, clean working tree
  • Approval gates: Prompts before fix (unless --yolo)
  • Test failure prompts: Asks for approval if tests fail
  • Protected branches: Integrates with sc-git-worktree protected branch safeguards
  • Error recovery: Actionable error messages with suggested fixes
  • Isolated environments: Worktrees prevent cross-contamination of fixes

Error Handling

Common errors and solutions:

Authentication Required

Error: GH.AUTH.REQUIRED
Solution: Run `gh auth login`

Rate Limit Exceeded

Error: GH.RATE_LIMIT
Solution: Wait for rate limit reset or use authenticated requests

Worktree Conflicts

Error: WORKTREE.DIRTY
Solution: Commit or stash changes, or use sc-git-worktree to clean up

See TROUBLESHOOTING.md for more details.

Version History

See CHANGELOG.md for version history and migration notes.

Support

License

MIT License - See repository root for details.