workflow-orchestration

name	workflow-orchestration
description	Phase coordination, agent handoffs, and workflow state machine management
triggers	["workflow","phase transition","orchestration","coordination"]

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

From	To	Condition
INIT	DISCUSS	Initialization complete
DISCUSS	PLAN	Requirements captured
PLAN	EXECUTE	Plan approved
EXECUTE	VERIFY	All tasks complete
EXECUTE	DISCUSS	Major scope change needed
EXECUTE	PLAN	Task restructure needed
VERIFY	COMPLETE	Sign-off received
VERIFY	EXECUTE	Issues need fixing

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

Phase	Progress Based On
INIT	Steps completed / total steps
DISCUSS	Areas explored / total areas
PLAN	Tasks defined / estimated total
EXECUTE	Tasks completed / total tasks
VERIFY	Checks passed / total checks

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