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:

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:

• INIT: 100%
• 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