claude-flow 3.28.0 → 3.29.0

package/.claude/commands/github/project-board-sync.md

@@ -1,471 +1,471 @@
-# Project Board Sync - GitHub Projects Integration
-
-## Overview
-Synchronize AI swarms with GitHub Projects for visual task management, progress tracking, and team coordination.
-
-## Core Features
-
-### 1. Board Initialization
-```bash
-# Connect swarm to GitHub Project using gh CLI
-# Get project details
-PROJECT_ID=$(gh project list --owner @me --format json | \
-  jq -r '.projects[] | select(.title == "Development Board") | .id')
-
-# Initialize swarm with project
-npx ruv-swarm github board-init \
-  --project-id "$PROJECT_ID" \
-  --sync-mode "bidirectional" \
-  --create-views "swarm-status,agent-workload,priority"
-
-# Create project fields for swarm tracking
-gh project field-create $PROJECT_ID --owner @me \
-  --name "Swarm Status" \
-  --data-type "SINGLE_SELECT" \
-  --single-select-options "pending,in_progress,completed"
-```
-
-### 2. Task Synchronization
-```bash
-# Sync swarm tasks with project cards
-npx ruv-swarm github board-sync \
-  --map-status '{
-    "todo": "To Do",
-    "in_progress": "In Progress",
-    "review": "Review",
-    "done": "Done"
-  }' \
-  --auto-move-cards \
-  --update-metadata
-```
-
-### 3. Real-time Updates
-```bash
-# Enable real-time board updates
-npx ruv-swarm github board-realtime \
-  --webhook-endpoint "https://api.example.com/github-sync" \
-  --update-frequency "immediate" \
-  --batch-updates false
-```
-
-## Configuration
-
-### Board Mapping Configuration
-```yaml
-# .github/board-sync.yml
-version: 1
-project:
-  name: "AI Development Board"
-  number: 1
-  
-mapping:
-  # Map swarm task status to board columns
-  status:
-    pending: "Backlog"
-    assigned: "Ready"
-    in_progress: "In Progress"
-    review: "Review"
-    completed: "Done"
-    blocked: "Blocked"
-    
-  # Map agent types to labels
-  agents:
-    coder: "🔧 Development"
-    tester: "🧪 Testing"
-    analyst: "📊 Analysis"
-    designer: "🎨 Design"
-    architect: "🏗️ Architecture"
-    
-  # Map priority to project fields
-  priority:
-    critical: "🔴 Critical"
-    high: "🟡 High"
-    medium: "🟢 Medium"
-    low: "⚪ Low"
-    
-  # Custom fields
-  fields:
-    - name: "Agent Count"
-      type: number
-      source: task.agents.length
-    - name: "Complexity"
-      type: select
-      source: task.complexity
-    - name: "ETA"
-      type: date
-      source: task.estimatedCompletion
-```
-
-### View Configuration
-```javascript
-// Custom board views
-{
-  "views": [
-    {
-      "name": "Swarm Overview",
-      "type": "board",
-      "groupBy": "status",
-      "filters": ["is:open"],
-      "sort": "priority:desc"
-    },
-    {
-      "name": "Agent Workload",
-      "type": "table",
-      "groupBy": "assignedAgent",
-      "columns": ["title", "status", "priority", "eta"],
-      "sort": "eta:asc"
-    },
-    {
-      "name": "Sprint Progress",
-      "type": "roadmap",
-      "dateField": "eta",
-      "groupBy": "milestone"
-    }
-  ]
-}
-```
-
-## Automation Features
-
-### 1. Auto-Assignment
-```bash
-# Automatically assign cards to agents
-npx ruv-swarm github board-auto-assign \
-  --strategy "load-balanced" \
-  --consider "expertise,workload,availability" \
-  --update-cards
-```
-
-### 2. Progress Tracking
-```bash
-# Track and visualize progress
-npx ruv-swarm github board-progress \
-  --show "burndown,velocity,cycle-time" \
-  --time-period "sprint" \
-  --export-metrics
-```
-
-### 3. Smart Card Movement
-```bash
-# Intelligent card state transitions
-npx ruv-swarm github board-smart-move \
-  --rules '{
-    "auto-progress": "when:all-subtasks-done",
-    "auto-review": "when:tests-pass",
-    "auto-done": "when:pr-merged"
-  }'
-```
-
-## Board Commands
-
-### Create Cards from Issues
-```bash
-# Convert issues to project cards using gh CLI
-# List issues with label
-ISSUES=$(gh issue list --label "enhancement" --json number,title,body)
-
-# Add issues to project
-echo "$ISSUES" | jq -r '.[].number' | while read -r issue; do
-  gh project item-add $PROJECT_ID --owner @me --url "https://github.com/$GITHUB_REPOSITORY/issues/$issue"
-done
-
-# Process with swarm
-npx ruv-swarm github board-import-issues \
-  --issues "$ISSUES" \
-  --add-to-column "Backlog" \
-  --parse-checklist \
-  --assign-agents
-```
-
-### Bulk Operations
-```bash
-# Bulk card operations
-npx ruv-swarm github board-bulk \
-  --filter "status:blocked" \
-  --action "add-label:needs-attention" \
-  --notify-assignees
-```
-
-### Card Templates
-```bash
-# Create cards from templates
-npx ruv-swarm github board-template \
-  --template "feature-development" \
-  --variables '{
-    "feature": "User Authentication",
-    "priority": "high",
-    "agents": ["architect", "coder", "tester"]
-  }' \
-  --create-subtasks
-```
-
-## Advanced Synchronization
-
-### 1. Multi-Board Sync
-```bash
-# Sync across multiple boards
-npx ruv-swarm github multi-board-sync \
-  --boards "Development,QA,Release" \
-  --sync-rules '{
-    "Development->QA": "when:ready-for-test",
-    "QA->Release": "when:tests-pass"
-  }'
-```
-
-### 2. Cross-Organization Sync
-```bash
-# Sync boards across organizations
-npx ruv-swarm github cross-org-sync \
-  --source "org1/Project-A" \
-  --target "org2/Project-B" \
-  --field-mapping "custom" \
-  --conflict-resolution "source-wins"
-```
-
-### 3. External Tool Integration
-```bash
-# Sync with external tools
-npx ruv-swarm github board-integrate \
-  --tool "jira" \
-  --mapping "bidirectional" \
-  --sync-frequency "5m" \
-  --transform-rules "custom"
-```
-
-## Visualization & Reporting
-
-### Board Analytics
-```bash
-# Generate board analytics using gh CLI data
-# Fetch project data
-PROJECT_DATA=$(gh project item-list $PROJECT_ID --owner @me --format json)
-
-# Get issue metrics
-ISSUE_METRICS=$(echo "$PROJECT_DATA" | jq -r '.items[] | select(.content.type == "Issue")' | \
-  while read -r item; do
-    ISSUE_NUM=$(echo "$item" | jq -r '.content.number')
-    gh issue view $ISSUE_NUM --json createdAt,closedAt,labels,assignees
-  done)
-
-# Generate analytics with swarm
-npx ruv-swarm github board-analytics \
-  --project-data "$PROJECT_DATA" \
-  --issue-metrics "$ISSUE_METRICS" \
-  --metrics "throughput,cycle-time,wip" \
-  --group-by "agent,priority,type" \
-  --time-range "30d" \
-  --export "dashboard"
-```
-
-### Custom Dashboards
-```javascript
-// Dashboard configuration
-{
-  "dashboard": {
-    "widgets": [
-      {
-        "type": "chart",
-        "title": "Task Completion Rate",
-        "data": "completed-per-day",
-        "visualization": "line"
-      },
-      {
-        "type": "gauge",
-        "title": "Sprint Progress",
-        "data": "sprint-completion",
-        "target": 100
-      },
-      {
-        "type": "heatmap",
-        "title": "Agent Activity",
-        "data": "agent-tasks-per-day"
-      }
-    ]
-  }
-}
-```
-
-### Reports
-```bash
-# Generate reports
-npx ruv-swarm github board-report \
-  --type "sprint-summary" \
-  --format "markdown" \
-  --include "velocity,burndown,blockers" \
-  --distribute "slack,email"
-```
-
-## Workflow Integration
-
-### Sprint Management
-```bash
-# Manage sprints with swarms
-npx ruv-swarm github sprint-manage \
-  --sprint "Sprint 23" \
-  --auto-populate \
-  --capacity-planning \
-  --track-velocity
-```
-
-### Milestone Tracking
-```bash
-# Track milestone progress
-npx ruv-swarm github milestone-track \
-  --milestone "v2.0 Release" \
-  --update-board \
-  --show-dependencies \
-  --predict-completion
-```
-
-### Release Planning
-```bash
-# Plan releases using board data
-npx ruv-swarm github release-plan-board \
-  --analyze-velocity \
-  --estimate-completion \
-  --identify-risks \
-  --optimize-scope
-```
-
-## Team Collaboration
-
-### Work Distribution
-```bash
-# Distribute work among team
-npx ruv-swarm github board-distribute \
-  --strategy "skills-based" \
-  --balance-workload \
-  --respect-preferences \
-  --notify-assignments
-```
-
-### Standup Automation
-```bash
-# Generate standup reports
-npx ruv-swarm github standup-report \
-  --team "frontend" \
-  --include "yesterday,today,blockers" \
-  --format "slack" \
-  --schedule "daily-9am"
-```
-
-### Review Coordination
-```bash
-# Coordinate reviews via board
-npx ruv-swarm github review-coordinate \
-  --board "Code Review" \
-  --assign-reviewers \
-  --track-feedback \
-  --ensure-coverage
-```
-
-## Best Practices
-
-### 1. Board Organization
-- Clear column definitions
-- Consistent labeling system
-- Regular board grooming
-- Automation rules
-
-### 2. Data Integrity
-- Bidirectional sync validation
-- Conflict resolution strategies
-- Audit trails
-- Regular backups
-
-### 3. Team Adoption
-- Training materials
-- Clear workflows
-- Regular reviews
-- Feedback loops
-
-## Troubleshooting
-
-### Sync Issues
-```bash
-# Diagnose sync problems
-npx ruv-swarm github board-diagnose \
-  --check "permissions,webhooks,rate-limits" \
-  --test-sync \
-  --show-conflicts
-```
-
-### Performance
-```bash
-# Optimize board performance
-npx ruv-swarm github board-optimize \
-  --analyze-size \
-  --archive-completed \
-  --index-fields \
-  --cache-views
-```
-
-### Data Recovery
-```bash
-# Recover board data
-npx ruv-swarm github board-recover \
-  --backup-id "2024-01-15" \
-  --restore-cards \
-  --preserve-current \
-  --merge-conflicts
-```
-
-## Examples
-
-### Agile Development Board
-```bash
-# Setup agile board
-npx ruv-swarm github agile-board \
-  --methodology "scrum" \
-  --sprint-length "2w" \
-  --ceremonies "planning,review,retro" \
-  --metrics "velocity,burndown"
-```
-
-### Kanban Flow Board
-```bash
-# Setup kanban board
-npx ruv-swarm github kanban-board \
-  --wip-limits '{
-    "In Progress": 5,
-    "Review": 3
-  }' \
-  --cycle-time-tracking \
-  --continuous-flow
-```
-
-### Research Project Board
-```bash
-# Setup research board
-npx ruv-swarm github research-board \
-  --phases "ideation,research,experiment,analysis,publish" \
-  --track-citations \
-  --collaborate-external
-```
-
-## Metrics & KPIs
-
-### Performance Metrics
-```bash
-# Track board performance
-npx ruv-swarm github board-kpis \
-  --metrics '[
-    "average-cycle-time",
-    "throughput-per-sprint",
-    "blocked-time-percentage",
-    "first-time-pass-rate"
-  ]' \
-  --dashboard-url
-```
-
-### Team Metrics
-```bash
-# Track team performance
-npx ruv-swarm github team-metrics \
-  --board "Development" \
-  --per-member \
-  --include "velocity,quality,collaboration" \
-  --anonymous-option
-```
-
+# Project Board Sync - GitHub Projects Integration
+
+## Overview
+Synchronize AI swarms with GitHub Projects for visual task management, progress tracking, and team coordination.
+
+## Core Features
+
+### 1. Board Initialization
+```bash
+# Connect swarm to GitHub Project using gh CLI
+# Get project details
+PROJECT_ID=$(gh project list --owner @me --format json | \
+  jq -r '.projects[] | select(.title == "Development Board") | .id')
+
+# Initialize swarm with project
+npx ruv-swarm github board-init \
+  --project-id "$PROJECT_ID" \
+  --sync-mode "bidirectional" \
+  --create-views "swarm-status,agent-workload,priority"
+
+# Create project fields for swarm tracking
+gh project field-create $PROJECT_ID --owner @me \
+  --name "Swarm Status" \
+  --data-type "SINGLE_SELECT" \
+  --single-select-options "pending,in_progress,completed"
+```
+
+### 2. Task Synchronization
+```bash
+# Sync swarm tasks with project cards
+npx ruv-swarm github board-sync \
+  --map-status '{
+    "todo": "To Do",
+    "in_progress": "In Progress",
+    "review": "Review",
+    "done": "Done"
+  }' \
+  --auto-move-cards \
+  --update-metadata
+```
+
+### 3. Real-time Updates
+```bash
+# Enable real-time board updates
+npx ruv-swarm github board-realtime \
+  --webhook-endpoint "https://api.example.com/github-sync" \
+  --update-frequency "immediate" \
+  --batch-updates false
+```
+
+## Configuration
+
+### Board Mapping Configuration
+```yaml
+# .github/board-sync.yml
+version: 1
+project:
+  name: "AI Development Board"
+  number: 1
+  
+mapping:
+  # Map swarm task status to board columns
+  status:
+    pending: "Backlog"
+    assigned: "Ready"
+    in_progress: "In Progress"
+    review: "Review"
+    completed: "Done"
+    blocked: "Blocked"
+    
+  # Map agent types to labels
+  agents:
+    coder: "🔧 Development"
+    tester: "🧪 Testing"
+    analyst: "📊 Analysis"
+    designer: "🎨 Design"
+    architect: "🏗️ Architecture"
+    
+  # Map priority to project fields
+  priority:
+    critical: "🔴 Critical"
+    high: "🟡 High"
+    medium: "🟢 Medium"
+    low: "⚪ Low"
+    
+  # Custom fields
+  fields:
+    - name: "Agent Count"
+      type: number
+      source: task.agents.length
+    - name: "Complexity"
+      type: select
+      source: task.complexity
+    - name: "ETA"
+      type: date
+      source: task.estimatedCompletion
+```
+
+### View Configuration
+```javascript
+// Custom board views
+{
+  "views": [
+    {
+      "name": "Swarm Overview",
+      "type": "board",
+      "groupBy": "status",
+      "filters": ["is:open"],
+      "sort": "priority:desc"
+    },
+    {
+      "name": "Agent Workload",
+      "type": "table",
+      "groupBy": "assignedAgent",
+      "columns": ["title", "status", "priority", "eta"],
+      "sort": "eta:asc"
+    },
+    {
+      "name": "Sprint Progress",
+      "type": "roadmap",
+      "dateField": "eta",
+      "groupBy": "milestone"
+    }
+  ]
+}
+```
+
+## Automation Features
+
+### 1. Auto-Assignment
+```bash
+# Automatically assign cards to agents
+npx ruv-swarm github board-auto-assign \
+  --strategy "load-balanced" \
+  --consider "expertise,workload,availability" \
+  --update-cards
+```
+
+### 2. Progress Tracking
+```bash
+# Track and visualize progress
+npx ruv-swarm github board-progress \
+  --show "burndown,velocity,cycle-time" \
+  --time-period "sprint" \
+  --export-metrics
+```
+
+### 3. Smart Card Movement
+```bash
+# Intelligent card state transitions
+npx ruv-swarm github board-smart-move \
+  --rules '{
+    "auto-progress": "when:all-subtasks-done",
+    "auto-review": "when:tests-pass",
+    "auto-done": "when:pr-merged"
+  }'
+```
+
+## Board Commands
+
+### Create Cards from Issues
+```bash
+# Convert issues to project cards using gh CLI
+# List issues with label
+ISSUES=$(gh issue list --label "enhancement" --json number,title,body)
+
+# Add issues to project
+echo "$ISSUES" | jq -r '.[].number' | while read -r issue; do
+  gh project item-add $PROJECT_ID --owner @me --url "https://github.com/$GITHUB_REPOSITORY/issues/$issue"
+done
+
+# Process with swarm
+npx ruv-swarm github board-import-issues \
+  --issues "$ISSUES" \
+  --add-to-column "Backlog" \
+  --parse-checklist \
+  --assign-agents
+```
+
+### Bulk Operations
+```bash
+# Bulk card operations
+npx ruv-swarm github board-bulk \
+  --filter "status:blocked" \
+  --action "add-label:needs-attention" \
+  --notify-assignees
+```
+
+### Card Templates
+```bash
+# Create cards from templates
+npx ruv-swarm github board-template \
+  --template "feature-development" \
+  --variables '{
+    "feature": "User Authentication",
+    "priority": "high",
+    "agents": ["architect", "coder", "tester"]
+  }' \
+  --create-subtasks
+```
+
+## Advanced Synchronization
+
+### 1. Multi-Board Sync
+```bash
+# Sync across multiple boards
+npx ruv-swarm github multi-board-sync \
+  --boards "Development,QA,Release" \
+  --sync-rules '{
+    "Development->QA": "when:ready-for-test",
+    "QA->Release": "when:tests-pass"
+  }'
+```
+
+### 2. Cross-Organization Sync
+```bash
+# Sync boards across organizations
+npx ruv-swarm github cross-org-sync \
+  --source "org1/Project-A" \
+  --target "org2/Project-B" \
+  --field-mapping "custom" \
+  --conflict-resolution "source-wins"
+```
+
+### 3. External Tool Integration
+```bash
+# Sync with external tools
+npx ruv-swarm github board-integrate \
+  --tool "jira" \
+  --mapping "bidirectional" \
+  --sync-frequency "5m" \
+  --transform-rules "custom"
+```
+
+## Visualization & Reporting
+
+### Board Analytics
+```bash
+# Generate board analytics using gh CLI data
+# Fetch project data
+PROJECT_DATA=$(gh project item-list $PROJECT_ID --owner @me --format json)
+
+# Get issue metrics
+ISSUE_METRICS=$(echo "$PROJECT_DATA" | jq -r '.items[] | select(.content.type == "Issue")' | \
+  while read -r item; do
+    ISSUE_NUM=$(echo "$item" | jq -r '.content.number')
+    gh issue view $ISSUE_NUM --json createdAt,closedAt,labels,assignees
+  done)
+
+# Generate analytics with swarm
+npx ruv-swarm github board-analytics \
+  --project-data "$PROJECT_DATA" \
+  --issue-metrics "$ISSUE_METRICS" \
+  --metrics "throughput,cycle-time,wip" \
+  --group-by "agent,priority,type" \
+  --time-range "30d" \
+  --export "dashboard"
+```
+
+### Custom Dashboards
+```javascript
+// Dashboard configuration
+{
+  "dashboard": {
+    "widgets": [
+      {
+        "type": "chart",
+        "title": "Task Completion Rate",
+        "data": "completed-per-day",
+        "visualization": "line"
+      },
+      {
+        "type": "gauge",
+        "title": "Sprint Progress",
+        "data": "sprint-completion",
+        "target": 100
+      },
+      {
+        "type": "heatmap",
+        "title": "Agent Activity",
+        "data": "agent-tasks-per-day"
+      }
+    ]
+  }
+}
+```
+
+### Reports
+```bash
+# Generate reports
+npx ruv-swarm github board-report \
+  --type "sprint-summary" \
+  --format "markdown" \
+  --include "velocity,burndown,blockers" \
+  --distribute "slack,email"
+```
+
+## Workflow Integration
+
+### Sprint Management
+```bash
+# Manage sprints with swarms
+npx ruv-swarm github sprint-manage \
+  --sprint "Sprint 23" \
+  --auto-populate \
+  --capacity-planning \
+  --track-velocity
+```
+
+### Milestone Tracking
+```bash
+# Track milestone progress
+npx ruv-swarm github milestone-track \
+  --milestone "v2.0 Release" \
+  --update-board \
+  --show-dependencies \
+  --predict-completion
+```
+
+### Release Planning
+```bash
+# Plan releases using board data
+npx ruv-swarm github release-plan-board \
+  --analyze-velocity \
+  --estimate-completion \
+  --identify-risks \
+  --optimize-scope
+```
+
+## Team Collaboration
+
+### Work Distribution
+```bash
+# Distribute work among team
+npx ruv-swarm github board-distribute \
+  --strategy "skills-based" \
+  --balance-workload \
+  --respect-preferences \
+  --notify-assignments
+```
+
+### Standup Automation
+```bash
+# Generate standup reports
+npx ruv-swarm github standup-report \
+  --team "frontend" \
+  --include "yesterday,today,blockers" \
+  --format "slack" \
+  --schedule "daily-9am"
+```
+
+### Review Coordination
+```bash
+# Coordinate reviews via board
+npx ruv-swarm github review-coordinate \
+  --board "Code Review" \
+  --assign-reviewers \
+  --track-feedback \
+  --ensure-coverage
+```
+
+## Best Practices
+
+### 1. Board Organization
+- Clear column definitions
+- Consistent labeling system
+- Regular board grooming
+- Automation rules
+
+### 2. Data Integrity
+- Bidirectional sync validation
+- Conflict resolution strategies
+- Audit trails
+- Regular backups
+
+### 3. Team Adoption
+- Training materials
+- Clear workflows
+- Regular reviews
+- Feedback loops
+
+## Troubleshooting
+
+### Sync Issues
+```bash
+# Diagnose sync problems
+npx ruv-swarm github board-diagnose \
+  --check "permissions,webhooks,rate-limits" \
+  --test-sync \
+  --show-conflicts
+```
+
+### Performance
+```bash
+# Optimize board performance
+npx ruv-swarm github board-optimize \
+  --analyze-size \
+  --archive-completed \
+  --index-fields \
+  --cache-views
+```
+
+### Data Recovery
+```bash
+# Recover board data
+npx ruv-swarm github board-recover \
+  --backup-id "2024-01-15" \
+  --restore-cards \
+  --preserve-current \
+  --merge-conflicts
+```
+
+## Examples
+
+### Agile Development Board
+```bash
+# Setup agile board
+npx ruv-swarm github agile-board \
+  --methodology "scrum" \
+  --sprint-length "2w" \
+  --ceremonies "planning,review,retro" \
+  --metrics "velocity,burndown"
+```
+
+### Kanban Flow Board
+```bash
+# Setup kanban board
+npx ruv-swarm github kanban-board \
+  --wip-limits '{
+    "In Progress": 5,
+    "Review": 3
+  }' \
+  --cycle-time-tracking \
+  --continuous-flow
+```
+
+### Research Project Board
+```bash
+# Setup research board
+npx ruv-swarm github research-board \
+  --phases "ideation,research,experiment,analysis,publish" \
+  --track-citations \
+  --collaborate-external
+```
+
+## Metrics & KPIs
+
+### Performance Metrics
+```bash
+# Track board performance
+npx ruv-swarm github board-kpis \
+  --metrics '[
+    "average-cycle-time",
+    "throughput-per-sprint",
+    "blocked-time-percentage",
+    "first-time-pass-rate"
+  ]' \
+  --dashboard-url
+```
+
+### Team Metrics
+```bash
+# Track team performance
+npx ruv-swarm github team-metrics \
+  --board "Development" \
+  --per-member \
+  --include "velocity,quality,collaboration" \
+  --anonymous-option
+```
+
 See also: [swarm-issue.md](./swarm-issue.md), [multi-repo-swarm.md](./multi-repo-swarm.md)