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 /specweave:github:* commands

---

How Task Tracking Works

1. Task Checklist in GitHub Issue

When creating an increment issue, automatically add task checklist:

## 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:

### ✅ 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

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

Method 2: Issue comments

@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:

### 🚨 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:

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

/specweave:github:status 0004

Output:

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

/specweave:github:sync 0004 --tasks

Updates GitHub issue checklist to match current increment progress.

Comment on Task

/specweave: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:

**@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:

### 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:

@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:

# .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:

/specweave:github:time-report 0004

Output:

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:

1. Backlog: Pending tasks
2. Ready: Tasks ready to start
3. In Progress: Currently being worked on
4. Review: PRs open, needs review
5. 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:

# .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:

### 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:

### 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:

### 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:

@developer1 you were assigned T-015 in #130

Blocking Notifications

Notify blocked task assignees when blocker resolves:

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

Deadline Reminders

Warn when tasks are behind schedule:

⚠️ 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: /specweave: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: /specweave:github:sync 0004 --force

---

Best Practices

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

---

Related

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

---

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