Issue Progress Tracking

Automatic GitHub issue progress tracking that updates issues based on commits and marks sub-tasks as complete.

Overview

• Working on GitHub issues with checkbox sub-tasks
• Making commits that reference issue numbers
• Using issue-prefixed branches (e.g., issue/123-feature, fix/456-bug)
• Wanting automatic progress visibility without manual updates

How It Works

Automatic Progress Tracking

The plugin automatically tracks your work through three coordinated hooks:

1. Commit Detection (issue-progress-commenter.sh)

   • Extracts issue number from branch name or commit message
   • Queues commit info for batch commenting
   • Supports patterns: issue/123-*, fix/123-*, feature/123-*, #123

2. Sub-task Updates (issue-subtask-updater.sh)

   • Parses commit messages for task completion keywords
   • Matches against unchecked - [ ] items in issue body
   • Automatically checks off matching tasks via GitHub API

3. Session Summary (issue-work-summary.sh)

   • Posts consolidated progress comment when session ends
   • Includes: commits, files changed, sub-tasks completed, PR link

Issue Number Extraction

# From branch name (priority)
issue/123-implement-feature  # Extracts: 123
fix/456-resolve-bug          # Extracts: 456
feature/789-add-tests        # Extracts: 789
123-some-description         # Extracts: 123

# From commit message (fallback)
"feat(#123): Add user validation"     # Extracts: 123
"fix: Resolve bug (closes #456)"      # Extracts: 456

Sub-task Matching

Commit messages are matched against issue checkboxes using:

• Normalized text comparison (case-insensitive)
• Partial matching for task descriptions
• Keyword detection (Add, Implement, Fix, Test, etc.)

Example:

# Issue body
- [ ] Add input validation
- [ ] Write unit tests
- [ ] Update documentation

# Commit message
"feat(#123): Add input validation"

# Result: First checkbox auto-checked
- [x] Add input validation
- [ ] Write unit tests
- [ ] Update documentation

Progress Comment Format

## Claude Code Progress Update

**Session**: `abc12345...`
**Branch**: `issue/123-implement-feature`

### Commits (3)
- `abc1234`: feat(#123): Add input validation
- `def5678`: test(#123): Add unit tests
- `ghi9012`: docs(#123): Update README

### Files Changed
- `src/validation.ts` (+45, -12)
- `tests/validation.test.ts` (+89, -0)
- `README.md` (+5, -2)

### Sub-tasks Completed
- [x] Add input validation
- [x] Write unit tests

### Pull Request
https://github.com/owner/repo/pull/42

---
*Automated by OrchestKit*

Requirements

• gh CLI installed and authenticated
• Repository with GitHub remote
• Issue must exist and be accessible

Configuration

Disable individual hooks in .claude/config.json:

{
  "hooks": {
    "issue-progress-commenter.sh": false,
    "issue-subtask-updater.sh": false,
    "issue-work-summary.sh": false
  }
}

PR-Aware Session Resumption (CC 2.1.27)

When working on issue-linked PRs, use --from-pr to resume sessions with full PR context:

claude --from-pr 42    # Resumes with PR diff, comments, review status

This enables progress tracking hooks to access PR metadata (review comments, CI status) when posting session summaries, giving richer progress updates on the linked issue.

Best Practices

1. Use Issue Branches: Start branches with issue/N- for automatic detection
2. Reference Issues in Commits: Include #N or (#N) in commit messages
3. Match Checkbox Text: Commit messages that match issue checkboxes get auto-checked
4. Use Conventional Commits: feat(#123):, fix(#123):, test(#123): patterns work well

Related Skills

• commit – Commit creation with conventional format
• github-operations – GitHub CLI patterns and workflows
• fix-issue – Issue resolution workflow

References

• Branch Naming – Supported branch patterns for issue extraction
• GitHub CLI Commands – gh commands used by the hooks