specweave 0.4.1 → 0.6.3

package/plugins/specweave-github/lib/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Type definitions for GitHub sync plugin
+ */
+
+export interface Task {
+  id: string; // e.g., "T-001"
+  title: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  estimate: string; // e.g., "2 hours"
+  status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+  githubIssue?: number; // GitHub issue number
+  assignee?: string; // GitHub username (without @)
+  description: string;
+  subtasks?: Subtask[];
+  filesToCreate?: string[];
+  filesToModify?: string[];
+  implementation?: string; // Code snippets
+  acceptanceCriteria?: string[];
+  dependencies?: string[]; // e.g., ["T-001", "T-002"]
+  blocks?: string[]; // e.g., ["T-005", "T-006"]
+  phase?: string; // e.g., "Phase 1: Foundation"
+}
+
+export interface Subtask {
+  id: string; // e.g., "S-001-01"
+  description: string;
+  estimate: string; // e.g., "30min"
+  completed: boolean;
+}
+
+export interface IncrementMetadata {
+  id: string; // e.g., "0004-plugin-architecture"
+  title: string;
+  version?: string; // e.g., "0.4.0"
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  status: 'planning' | 'in-progress' | 'completed' | 'cancelled';
+  github?: {
+    milestone?: number; // GitHub milestone number
+    epic_issue?: number; // Epic issue number
+    task_issues?: Record<string, number>; // Task ID → GitHub issue number
+    last_sync?: string; // ISO timestamp
+  };
+}
+
+export interface GitHubIssue {
+  number: number;
+  title: string;
+  body: string;
+  state: 'open' | 'closed';
+  html_url: string;
+  labels: string[];
+  milestone?: {
+    number: number;
+    title: string;
+  };
+}
+
+export interface GitHubMilestone {
+  number: number;
+  title: string;
+  description: string;
+  state: 'open' | 'closed';
+}
+
+export interface SyncResult {
+  milestone?: GitHubMilestone;
+  epic: GitHubIssue;
+  tasks: Array<{
+    taskId: string;
+    issue: GitHubIssue;
+  }>;
+  errors: Array<{
+    taskId?: string;
+    error: string;
+  }>;
+}
+
+export interface GitHubSyncOptions {
+  force?: boolean; // Overwrite existing issues
+  dryRun?: boolean; // Don't actually create issues
+  batchDelay?: number; // Delay between batches (ms, default: 6000)
+  batchSize?: number; // Issues per batch (default: 10)
+  milestoneDays?: number; // Days until milestone due (default: 2 - SpecWeave AI velocity)
+  projectName?: string; // Optional: Add issues to GitHub Project (e.g., "SpecWeave v0.4.0")
+  fastMode?: boolean; // Skip rate limiting (for increments < 10 tasks)
+}

package/plugins/specweave-github/skills/github-issue-tracker/SKILL.md

@@ -0,0 +1,497 @@
+---
+name: github-issue-tracker
+description: Task-level GitHub issue tracking for SpecWeave increments. Provides fine-grained progress tracking via issue comments, task checklists, and labels. Enables team collaboration on individual tasks. Activates for task tracking, GitHub comments, issue updates, task progress, team collaboration, granular tracking.
+---
+
+# 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:
+
+```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**
+```
+@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
+/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
+
+```bash
+/specweave:github:sync 0004 --tasks
+```
+
+Updates GitHub issue checklist to match current increment progress.
+
+### Comment on Task
+
+```bash
+/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:
+
+```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
+/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:
+
+```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:
+
+```
+@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