Copilot Workflow Orchestrator

1. Define workflow phases - Break work into sequential or parallel phases
2. Manage handoffs - Ensure smooth transitions between agents
3. Monitor progress - Track which agents have completed their work
4. Unblock dependencies - Automatically assign next agent when dependencies clear
5. Ensure quality - Coordinate reviews and testing throughout workflow

Core Concepts

Workflow

A coordinated sequence of work items (issues) with dependencies, assigned to appropriate agents.

Phase

A logical grouping of work that can happen in parallel. Phases execute sequentially.

Handoff

The transition point when one agent completes work and the next agent can start.

Checkpoint

A verification point where progress is validated before proceeding to next phase.

Workflow Types

See workflows/ directory for pre-defined workflow templates:

1. Full-Stack Feature Workflow

Phase 1: Backend Foundation
  └─ Database Specialist → Schema changes

Phase 2: API Implementation
  └─ Backend API Specialist → Endpoints (depends on Phase 1)

Phase 3: Frontend Implementation
  ├─ React Specialist → Components (depends on Phase 2)
  └─ Tailwind UI Specialist → Styling (depends on Phase 2)

Phase 4: Integration & Testing
  ├─ State Management Specialist → Wire up data flow
  └─ Testing Specialist → E2E tests

Phase 5: Review & Polish
  ├─ Code Review Specialist → Review all changes
  ├─ Performance Specialist → Check performance
  └─ Security Specialist → Security review

2. Refactoring Workflow

Phase 1: Preparation
  └─ Testing Specialist → Add tests for existing behavior

Phase 2: Refactoring
  └─ Refactoring Specialist → Restructure code

Phase 3: Verification
  ├─ TypeScript Specialist → Fix type issues
  └─ Testing Specialist → Verify tests still pass

Phase 4: Review
  └─ Code Review Specialist → Ensure no behavior changes

3. Integration Workflow

Phase 1: Authentication
  ├─ Authentication Specialist → OAuth flow
  └─ Security Specialist → Token security

Phase 2: API Integration
  └─ [Service] API Specialist → API calls

Phase 3: Frontend
  ├─ React Specialist → UI components
  └─ State Management Specialist → Data flow

Phase 4: Testing
  └─ Testing Specialist → Integration tests

Workflow Management

1. Workflow Creation

When creating a workflow:

{
  id: "workflow-123",
  epic: "#150",
  name: "Spotify Playlist Integration",
  phases: [
    {
      name: "Authentication",
      issues: ["#151"],
      agents: ["Third-Party-API-Specialist", "Authentication-Specialist"],
      dependencies: [],
      checkpoint: "OAuth flow working, tokens stored"
    },
    {
      name: "API Implementation",
      issues: ["#152", "#153"],
      agents: ["Third-Party-API-Specialist", "Backend-API-Specialist"],
      dependencies: ["Phase 1"],
      checkpoint: "API endpoints return playlist data"
    },
    // ... more phases
  ],
  status: "in_progress",
  currentPhase: 1
}

2. Phase Execution

For each phase:

1. Check dependencies - Ensure previous phases complete via GitHub MCP
2. Assign agents - Use mcp__github__assign_copilot_to_issue for each issue
3. Monitor progress - Real-time PR monitoring via mcp__github__pull_request_read
   • Track PR creation (agents open PRs)
   • Monitor CI/CD checks status
   • Watch review comments
   • Detect when PR is merged
4. Validate checkpoint - Verify phase goals met
   • All issues closed
   • All PRs merged
   • Tests passing
   • Checkpoint criteria satisfied
5. Proceed to next - Trigger next phase automatically when ready

3. Handoff Management

When transitioning between phases:

## Phase Handoff: Authentication → API Implementation

**Previous Phase**: Authentication ✅ Completed
- #151 merged in PR #200
- OAuth flow working
- Tokens stored securely

**Next Phase**: API Implementation 🚀 Starting
- Agents: @Third-Party-API-Specialist, @Backend-API-Specialist
- Issues: #152, #153
- Context: Use OAuth tokens from Phase 1 to make Spotify API calls

**Handoff Notes**:
- Token storage methods available in `server/storage.ts:456`
- OAuth callback route is `/api/spotify/callback`
- Access tokens expire after 1 hour, use refresh logic

**Checkpoint**: API endpoints should return playlist data successfully

4. Progress Tracking

Track workflow status:

Workflow: Spotify Playlist Integration (#150)
Status: Phase 2 of 4 (50% complete)

✅ Phase 1: Authentication (Completed 2 hours ago)
   - #151: Spotify OAuth flow → Merged in PR #200

🚀 Phase 2: API Implementation (In Progress)
   - #152: Playlist search API → PR #201 (in review)
   - #153: Track metadata API → Assigned, not started

⏳ Phase 3: Frontend (Blocked - waiting on Phase 2)
   - #154: Playlist browser UI
   - #155: Playback controls

⏳ Phase 4: Testing (Blocked - waiting on Phase 3)
   - #156: E2E tests for playlist flow

Workflow Monitoring (Real-Time via GitHub MCP)

Automatic Progress Detection

Using GitHub MCP tools to monitor in real-time:

• PR creation - Use mcp__github__search_pull_requests to find new PRs
• PR status - Use mcp__github__pull_request_read with method: "get"
• CI/CD checks - Use mcp__github__pull_request_read with method: "get_status"
• Review status - Use mcp__github__pull_request_read with method: "get_reviews"
• PR merge - Detect when pr.merged === true
• Issue status - Use mcp__github__issue_read to check if closed

Monitoring Loop

// Poll every 5 minutes
while (!phaseComplete) {
  for (const issueNum of phaseIssues) {
    const issue = await mcp__github__issue_read({
      method: "get",
      owner: "{owner}",
      repo: "{repo}",
      issue_number: issueNum
    })

    // Check if issue has linked PR
    if (issue.pull_request) {
      const pr = await mcp__github__pull_request_read({
        method: "get",
        owner: "{owner}",
        repo: "{repo}",
        pullNumber: issue.pull_request.number
      })

      // Track progress
      if (pr.merged) {
        markIssueComplete(issueNum)
      }
    }
  }

  await sleep(300000) // 5 minutes
}

Checkpoint Validation

Before moving to next phase, validate via GitHub MCP:

1. All issues closed - Use mcp__github__issue_read to verify state === "closed"
2. All PRs merged - Check pr.merged === true for each PR
3. Tests passing - Use pull_request_read with method: "get_status"
   • Verify all checks have conclusion: "success"
4. No blocking issues - Search for P0/P1 bugs created during phase
5. Checkpoint criteria met - Custom validation per workflow

Progress Notifications

Update epic issue with progress:

## Workflow Progress

**Last Updated**: 2025-01-15 14:30 UTC

### Phase 1: Authentication ✅
- #151 Completed (PR #200)

### Phase 2: API Implementation 🚀 IN PROGRESS
- #152 In Review (PR #201)
- #153 Not Started

### Phase 3: Frontend ⏳ BLOCKED
Waiting on #152, #153

### Phase 4: Testing ⏳ BLOCKED
Waiting on #154, #155

**Overall Progress**: 25% (1/4 phases complete)
**Estimated Completion**: 3-4 days remaining

Conflict Resolution

Agent Conflicts

When two agents need to modify the same file:

1. Sequential assignment - Assign agents in order
2. Clear boundaries - Define which agent owns which sections
3. Communication - Add notes about shared files in assignments

Merge Conflicts

When PRs conflict:

1. Detect conflict - Monitor PR status
2. Coordinate resolution - Assign to agent who opened later PR
3. Re-review - Code Review Specialist reviews conflict resolution

Blocking Issues

When new bugs block workflow:

1. Create blocking issue - File as P0/P1
2. Pause workflow - Mark current phase as blocked
3. Assign fix - Route to appropriate agent
4. Resume - Continue workflow when fixed

Workflow Templates

Pre-defined workflows in workflows/ directory:

• full-stack-feature.md - Complete backend + frontend feature
• api-integration.md - Third-party API integration
• refactoring.md - Safe code refactoring workflow
• performance-optimization.md - Performance improvement workflow
• security-hardening.md - Security improvement workflow
• testing-pyramid.md - Comprehensive test coverage workflow

Integration with Other Skills

After github-mcp-orchestrator + copilot-agent-coordinator

Typical flow:

1. Orchestrator creates epic + child issues
2. Coordinator assigns agents to issues
3. Workflow Orchestrator (this skill) manages execution sequencing
4. PR Reviewer reviews completed work

Workflow Lifecycle

Issue Creation → Agent Assignment → Workflow Orchestration → PR Review → Merge
     ↑                ↑                      ↑                   ↑          ↑
     |                |                      |                   |          |
MCP Orchestrator  Agent Coordinator   Workflow Orchestrator  PR Reviewer  Done

Reference Documentation

• Workflow templates: See workflows/ directory
• Handoff patterns: See reference/handoff-patterns.md
• Monitoring guide: See reference/monitoring.md

What This Skill Does

• Creates and manages multi-phase workflows
• Coordinates agent handoffs between phases
• Monitors workflow progress
• Validates phase checkpoints
• Updates epic with progress
• Detects and resolves blockers
• Ensures quality gates are met

What This Skill Doesn't Do

• Doesn't write code (agents do that)
• Doesn't review code (Code Review agent does that)
• Doesn't create issues (github-mcp-orchestrator does that)
• Doesn't assign individual agents (copilot-agent-coordinator does that)
• Doesn't execute CI/CD (GitHub Actions does that)

Output Format

Workflow Status Report

# Workflow Status: [Workflow Name]

**Epic**: #[NUM]
**Started**: [Date]
**Current Phase**: [N of M]
**Overall Status**: [On Track | At Risk | Blocked]

## Phase Summary

### ✅ Completed Phases
- Phase 1: [Name] (Completed [date])
  - Issues: #X, #Y
  - PRs: #A, #B

### 🚀 Active Phase
- Phase 2: [Name] (In Progress)
  - Issues: #C (in review), #D (assigned)
  - Blockers: None
  - Checkpoint: [Criteria]

### ⏳ Upcoming Phases
- Phase 3: [Name] (Blocked by Phase 2)
- Phase 4: [Name] (Blocked by Phase 3)

## Next Actions
1. [Action 1]
2. [Action 2]

## Risks
- [Risk 1] - [Mitigation]
- [Risk 2] - [Mitigation]

**Estimated Completion**: [Date / Days remaining]