GitHub Issue Tracker - Task-Level Progress Tracking

Purpose: Provide fine-grained task-level visibility in GitHub issues for detailed progress tracking and team collaboration.

When to Use:

•Detailed progress tracking (per-task updates)
•Team collaboration on specific tasks
•Task assignments via GitHub
•Blocking issue tracking
•Task-level comments and discussions

Integration: Works with github-sync skill and /sw:github:* commands

How Task Tracking Works

1. Task Checklist in GitHub Issue

When creating an increment issue, automatically add task checklist:

markdown

## Tasks

### Week 1: Foundation (12 tasks)

- [ ] T-001: Create plugin type definitions (6h) @developer1
- [ ] T-002: Create plugin manifest schema (4h) @developer1
- [ ] T-003: Implement PluginLoader (6h) @developer2
- [ ] T-004: Implement PluginManager (8h) @developer2
...

### Week 2: GitHub Plugin (10 tasks)

- [ ] T-013: Create GitHub plugin structure (2h)
- [ ] T-014: Implement github-sync skill (8h)
...

Features:

•Clickable checkboxes (GitHub native)
•Time estimates in parentheses
•Assignees via @mentions
•Organized by phase/week

2. Per-Task Comments

After each task completion, post detailed comment:

markdown

### ✅ Task Completed: T-007

**Title**: Implement Claude plugin installer
**Estimated**: 8h
**Actual**: 7h
**Assignee**: @developer2

**What Changed**:
- Added `compilePlugin()` method to ClaudeAdapter
- Implemented plugin file copying to `.claude/`
- Added unload and status methods
- Updated adapter interface

**Files Modified**:
- `src/adapters/claude/adapter.ts` (+150 lines)
- `src/adapters/adapter-interface.ts` (+35 lines)

**Tests**:
- ✅ Unit tests passing (12 new tests)
- ✅ Integration test: plugin install/uninstall

**Next Task**: T-008 - Implement Cursor plugin compiler

---

**Progress**: 7/48 tasks (15%) | Week 1: 7/12 complete

🤖 Posted by SpecWeave at 2025-10-30 14:30:00

Benefits:

•Detailed change log per task
•Time tracking (estimated vs actual)
•File change summary
•Test status
•Context for code reviewers

3. Task Assignments

Assign tasks to team members via GitHub:

Method 1: Task checklist with @mentions

markdown

- [ ] T-015: Create test suite (8h) @qa-engineer

Method 2: Issue comments

code

@developer1 Can you take T-003 and T-004 this week?

Method 3: GitHub Projects

•Drag tasks to columns (To Do, In Progress, Done)
•Auto-sync with increment status

4. Blocking Issues

Track dependencies and blockers:

markdown

### 🚨 Blocked: T-020

**Task**: Implement Kubernetes plugin
**Blocked By**: #127 (Infrastructure setup incomplete)
**Blocking**: T-021, T-022
**Reason**: Need staging cluster before testing K8s plugin

**Resolution**: Wait for #127 to close, then proceed with T-020

---

**ETA**: Blocked since 2025-10-28, expected resolution by 2025-11-01

Configuration

Enable task-level tracking in .specweave/config.yaml:

yaml

plugins:
  settings:
    specweave-github:
      # Task-level tracking
      task_tracking:
        enabled: true

        # Post comment after each task
        post_task_comments: true

        # Update checklist after each task
        update_checklist: true

        # Include file changes in comments
        include_file_changes: true

        # Include time tracking
        include_time_tracking: true

        # Auto-assign tasks based on git author
        auto_assign: true

      # Blocking issue detection
      blocking_issues:
        enabled: true

        # Check for blocking keywords in task descriptions
        keywords: ["blocked by", "depends on", "requires"]

Commands

Check Task Status

bash

/sw:github:status 0004

Output:

code

GitHub Issue: #130
Status: Open (In Progress)

Tasks: 7/48 completed (15%)

Week 1: Foundation
✅ T-001: Create plugin types (Done)
✅ T-002: Create manifest schema (Done)
✅ T-003: Implement PluginLoader (Done)
✅ T-004: Implement PluginManager (Done)
✅ T-005: Implement PluginDetector (Done)
✅ T-006: Update adapter interface (Done)
✅ T-007: Implement Claude installer (Done)
⏳ T-008: Implement Cursor compiler (In Progress)
⏸️ T-009: Implement Copilot compiler (Pending)

Sync Task Checklist

bash

/sw:github:sync 0004 --tasks

Updates GitHub issue checklist to match current increment progress.

Comment on Task

bash

/sw:github:comment 0004 T-008 "Cursor adapter completed, moving to testing phase"

Posts custom comment to GitHub issue for specific task.

GitHub Labels for Tasks

Automatically apply labels based on task status:

Label	When Applied	Purpose
`in-progress`	First task starts	Increment is actively being worked on
`testing`	Implementation tasks done	Ready for QA
`blocked`	Task marked as blocked	Needs attention
`review-requested`	PR created	Code review needed
`ready-for-merge`	Review approved	Can be merged

Team Collaboration Patterns

Pattern 1: Daily Standups via GitHub

Team members comment on tasks with daily updates:

markdown

**@developer1** on T-008:
Yesterday: Implemented Cursor adapter skeleton
Today: Adding plugin compilation logic
Blockers: None

**@developer2** on T-014:
Yesterday: Created github-sync skill
Today: Testing sync workflow
Blockers: Waiting for #130 review

Pattern 2: Code Review Integration

Link PRs to tasks:

markdown

### T-007: Claude plugin installer

**PR**: #45
**Status**: Ready for review
**Reviewers**: @tech-lead, @architect

**Changes**:
- Implemented plugin support in Claude adapter
- Added comprehensive tests
- Updated documentation

**Review Checklist**:
- [ ] Code quality (clean, readable)
- [ ] Test coverage (80%+)
- [ ] Documentation updated
- [ ] No security issues

Pattern 3: Task Handoff

Transfer task ownership:

markdown

@developer1 → @developer2 (T-015)

**Context**:
- Tests framework configured
- Need to write E2E tests for plugin system
- Reference: T-007 implementation

**Handoff Notes**:
- Use Playwright for E2E tests
- Cover happy path + error scenarios
- See `.specweave/increments/0004/tests.md` for test cases

Time Tracking

Automatic Time Tracking

Track time spent on tasks:

yaml

# .specweave/increments/0004-plugin-architecture/.metadata.yaml
tasks:
  T-007:
    estimated_hours: 8
    actual_hours: 7
    started_at: 2025-10-30T10:00:00Z
    completed_at: 2025-10-30T17:00:00Z
    assignee: developer2

Time Reports

Generate time reports:

bash

/sw:github:time-report 0004

Output:

code

Time Report: Increment 0004

Estimated: 240 hours (6 weeks)
Actual: 56 hours (1.4 weeks)
Remaining: 184 hours (4.6 weeks)

By Developer:
- developer1: 24h (5 tasks)
- developer2: 32h (2 tasks)

By Phase:
- Week 1 Foundation: 56h / 96h (58%)
- Week 2 GitHub Plugin: 0h / 80h (0%)
- Week 3 Plugins: 0h / 120h (0%)
- Week 4 Docs: 0h / 88h (0%)

Pace: On track (4% ahead of schedule)

GitHub Projects Integration

Automated Kanban Board

Sync increment tasks with GitHub Projects:

Board Columns:

•Backlog: Pending tasks
•Ready: Tasks ready to start
•In Progress: Currently being worked on
•Review: PRs open, needs review
•Done: Completed tasks

Auto-Move Rules:

•Task starts → Move to "In Progress"
•PR created → Move to "Review"
•PR merged → Move to "Done"

Milestone Tracking

Link increments to GitHub Milestones:

yaml

# .specweave/config.yaml
plugins:
  settings:
    specweave-github:
      milestones:
        "v0.4.0":
          increments:
            - 0004-plugin-architecture
            - 0005-user-authentication
          due_date: 2025-11-30

GitHub Milestone view shows progress across multiple increments.

Advanced Features

Task Dependencies

Define task dependencies in tasks.md:

markdown

### T-008: Implement Cursor compiler

**Dependencies**: T-006, T-007
**Blocks**: T-011, T-012

**Description**: ...

SpecWeave enforces dependency order and warns if attempting blocked task.

Subtasks

Break complex tasks into subtasks:

markdown

### T-014: Implement github-sync skill (8h)

**Subtasks**:
- [ ] T-014.1: Create SKILL.md (1h)
- [ ] T-014.2: Implement export (increment → issue) (3h)
- [ ] T-014.3: Implement import (issue → increment) (2h)
- [ ] T-014.4: Add progress updates (1h)
- [ ] T-014.5: Write tests (1h)

Subtasks appear as nested checkboxes in GitHub issue.

External Issue Links

Reference external blocking issues:

markdown

### T-020: Kubernetes plugin

**Blocked By**:
- #127 (this repo): Infrastructure setup
- https://github.com/kubernetes/kubernetes/issues/12345: K8s API bug

**Resolution Plan**:
1. Wait for #127 (ETA: 2025-11-01)
2. Work around K8s bug using alternative API

Notifications

Task Assignment Notifications

GitHub automatically notifies assignees:

code

@developer1 you were assigned T-015 in #130

Blocking Notifications

Notify blocked task assignees when blocker resolves:

code

@developer2 Task T-020 is unblocked (#127 was closed)

Deadline Reminders

Warn when tasks are behind schedule:

code

⚠️ T-008 is 2 days overdue (estimated: 2 days, actual: 4 days)

Troubleshooting

Checklist not updating?

•Verify update_checklist: true in config
•Check GitHub API permissions (repo write access)
•Manually sync: /sw:github:sync 0004 --tasks

Comments not posting?

•Check post_task_comments: true
•Verify GitHub CLI authenticated: gh auth status
•Check rate limits: gh api rate_limit

Time tracking inaccurate?

•Verify task timestamps in .metadata.yaml
•Check for manual edits to metadata
•Re-sync: /sw:github:sync 0004 --force

Best Practices

•Keep Tasks Atomic: Each task should be completable in one work session (2-8 hours)
•Update Checklists Daily: Sync progress at least once per day
•Use Assignees: Assign tasks to specific developers for accountability
•Track Blockers: Immediately flag blocking issues for visibility
•Link PRs: Always reference task ID in PR title (T-007: Add plugin support)
•Comment Context: Add context comments when handing off tasks
•Review Time Estimates: Adjust estimates based on actual time tracked

•github-sync: High-level increment ↔ issue synchronization
•github-manager agent: AI agent for GitHub operations
•Commands: All /sw:github:* commands

Version: 1.0.0 Plugin: specweave-github Last Updated: 2025-10-30

github-issue-tracker

GitHub Issue Tracker - Task-Level Progress Tracking

How Task Tracking Works

1. Task Checklist in GitHub Issue

2. Per-Task Comments

3. Task Assignments

4. Blocking Issues

Configuration

Commands

Check Task Status

Sync Task Checklist

Comment on Task

GitHub Labels for Tasks

Team Collaboration Patterns

Pattern 1: Daily Standups via GitHub

Pattern 2: Code Review Integration

Pattern 3: Task Handoff

Time Tracking

Automatic Time Tracking

Time Reports

GitHub Projects Integration

Automated Kanban Board

Milestone Tracking

Advanced Features

Task Dependencies

Subtasks

External Issue Links

Notifications

Task Assignment Notifications

Blocking Notifications

Deadline Reminders

Troubleshooting

Best Practices

Related