Workflow Orchestration

Workflow Orchestration Skill

This skill provides patterns for coordinating workflow phases, managing agent handoffs, and maintaining the workflow state machine.

Workflow State Machine

Phase States

        ┌─────────────────────────────────────────────────┐
        │                                                 │
        v                                                 │
┌──────────┐    ┌─────────┐    ┌──────────┐    ┌────────┐ │ ┌──────────┐
│   INIT   │ -> │ DISCUSS │ -> │   PLAN   │ -> │EXECUTE │-┘>│  VERIFY  │
└──────────┘    └─────────┘    └──────────┘    └────────┘   └──────────┘
                    ^               ^              │              │
                    │               │              │              │
                    └───────────────┴──────────────┘              │
                          (on issues found)                       │
                                                                  v
                                                            ┌──────────┐
                                                            │ COMPLETE │
                                                            └──────────┘

Valid Transitions

Invalid Transitions

• INIT → PLAN (must discuss first)
• INIT → EXECUTE (must plan first)
• VERIFY → DISCUSS (must execute changes)
• COMPLETE → any (workflow finished)

Phase Coordination

Phase Entry Protocol

Before entering any phase:

1. VERIFY previous phase complete
   - Check completion criteria
   - Verify artifacts exist
   - No active blockers

2. CREATE checkpoint in ITEM-XXX.md
   - Snapshot current state
   - Record transition reason
   - Note timestamp

3. UPDATE phase status
   - Set new phase
   - Reset progress to 0%
   - Record start time

4. PREPARE phase context
   - Load relevant state files
   - Identify agents needed
   - Clear stale context

Phase Exit Protocol

Before exiting any phase:

1. VERIFY completion criteria
   - Phase-specific requirements met
   - Artifacts created
   - No pending decisions

2. CREATE phase summary
   - What was accomplished
   - Decisions made
   - Artifacts produced

3. HANDOFF to next phase
   - What next phase needs to know
   - Key context to carry forward
   - Warnings or considerations

Agent Handoff Protocols

Spawning an Agent

## Agent Spawn: [agent-name]

**Purpose**: [Clear objective]

**Context provided**:
- Phase: [current phase]
- Task: [specific task if applicable]
- Key decisions: [relevant decisions]
- Files: [files to read]

**Expected deliverable**:
- [What agent should produce]
- [Format expected]

**Constraints**:
- [Time/scope limits]
- [Must follow conventions]
- [Report blockers immediately]

Receiving Agent Results

## Agent Result: [agent-name]

**Status**: [SUCCESS/PARTIAL/FAILED]

**Deliverables**:
- [What was produced]
- [Where it's stored]

**Key findings**:
- [Important discovery]
- [Important discovery]

**Issues encountered**:
- [Issue if any]

**Next recommended action**:
- [What to do next]

Multi-Agent Coordination

When multiple agents needed:

## Coordination Plan

**Agents involved**:
1. [Agent A]: [Purpose]
2. [Agent B]: [Purpose]

**Sequence**:
A -> B (B depends on A's output)

**Handoff points**:
- A completes: [deliverable] -> B starts
- B completes: [deliverable] -> next phase

**Fallback**:
- If A fails: [contingency]
- If B fails: [contingency]

Blocker Management

Blocker Detection

Watch for:

• Explicit blockers from agents
• Missing prerequisites
• User unavailability
• Technical failures
• Conflicts requiring resolution

Blocker Response

## Blocker Detected

**Type**: [Technical/Decision/External/Conflict]
**Phase**: [current phase]
**Impact**: [what's blocked]

**Options**:
1. Resolve blocker directly
2. Work around blocker
3. Pause workflow
4. Escalate to user

**Recommended**: [option]

Blocker Resolution Tracking

In ITEM-XXX.md:

### BLOCKER-XXX: [Title]
**Status**: ACTIVE -> RESOLVED
**Detected**: [timestamp]
**Resolved**: [timestamp]
**Resolution**: [what was done]
**Impact on workflow**: [any changes made]

Progress Tracking

Phase Progress Calculation

Progress Reporting

## Workflow Progress

**Overall**: [X]%
**Phase**: [current phase] at [Y]%

**Phase breakdown**:
- [x] INIT: 100%
- [x] DISCUSS: 100%
- [ ] PLAN: 75%
- [ ] EXECUTE: 0%
- [ ] VERIFY: 0%

**Blockers**: [count]
**Next milestone**: [description]

Rollback and Recovery

Phase Rollback

When needing to return to earlier phase:

## Phase Rollback

**From**: [current phase]
**To**: [target phase]
**Reason**: [why rolling back]

**Actions**:
1. Save current state as checkpoint
2. Preserve completed work
3. Update phase status
4. Clear invalid artifacts (if any)
5. Resume from target phase

Recovery from Failure

## Workflow Recovery

**Failure point**: [where it failed]
**Error**: [what happened]

**Recovery options**:
1. Retry from checkpoint
2. Skip failed item
3. Manual intervention
4. Abort with state preserved

**State preserved at**: .flow/FLOW.md and .flow/items/ITEM-XXX.md
**Resume command**: /flow-workflow:go

Quick Mode Orchestration

For /flow-workflow:quick:

## Quick Mode Flow

**Simplified phases**:
ASSESS -> CLARIFY -> IMPLEMENT -> VERIFY

**Shortcuts taken**:
- No FLOW.md or ITEM-XXX.md files created
- No detailed requirements gathering
- Direct execution
- Brief verification

**Escalation trigger**:
If complexity exceeds quick mode, escalate to full workflow with /flow-workflow:start

Integration Points

With State Management

• Update FLOW.md and ITEM-XXX.md on every transition
• Create checkpoints in ITEM-XXX.md at key points
• Maintain phase history in ITEM-XXX.md

With Capability Discovery

• Route to appropriate agents based on FLOW.md cache
• Announce delegation decisions with reasoning
• Fallback to defaults when no match
• Log capability gaps in FLOW.md

With Conflict Detection

• Block transitions on active conflicts
• Require resolution before proceeding
• Document resolved conflicts in ITEM-XXX.md

With Context Engineering

• Fresh context per task
• Coordinator stays under 40%
• Spawn fresh agents when approaching threshold