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

Agent Handoff Protocols

Overview

This document defines the protocols for passing work between agents in the flow-workflow system. Clean handoffs ensure context is preserved while keeping each agent focused.

Handoff Types

1. Phase Handoff

Transfer control between phases (DISCUSS → PLAN, PLAN → EXECUTE, etc.)

Protocol:

## Phase Handoff: [FROM] → [TO]

**Completed in [FROM]**:
- [Summary of accomplishments]

**Artifacts for [TO]**:
- [file]: [what it contains]

**Key context**:
- [Decision or finding relevant to next phase]

**Recommended first action**:
- [What the next phase should start with]

Example - DISCUSS → PLAN:

## Phase Handoff: DISCUSS → PLAN

**Completed in DISCUSS**:
- 5 areas explored
- 12 decisions made
- 8 functional requirements identified

**Artifacts for PLAN**:
- ITEM-XXX.md: 8 FR, 3 NFR documented, full exploration map, decisions recorded

**Key context**:
- Auth must use OAuth (DECISION-004)
- Performance target: <200ms response (NFR-001)
- Database: PostgreSQL (DECISION-007)

**Recommended first action**:
- Create tasks for FR-001 (user registration) first

---

2. Task Handoff

Transfer a specific task to an executor agent

Protocol:

## Task Handoff: TASK-XXX

**Task definition**:
[XML task from ITEM-XXX.md Tasks section]

**Context**:
- Preceding tasks: [completed tasks that affect this one]
- Key decisions: [relevant decisions]
- Patterns to follow: [established patterns]

**Files to read**:
- [path]: [why]

**Success criteria**:
- [from task <done>]

**Report back**:
- Task status (completed/blocked)
- Files modified
- Commit created (or error encountered)

Example:

## Task Handoff: TASK-005

**Task definition**:
<task id="TASK-005" status="pending">
  <name>Add email validation to registration</name>
  <description>Implement email format validation</description>
  <files>
    <file action="modify">src/services/UserService.ts</file>
    <file action="modify">src/validators/index.ts</file>
  </files>
  <actions>
    <action>Add validateEmail function to validators</action>
    <action>Call validator in UserService.register</action>
    <action>Return appropriate error on invalid email</action>
  </actions>
  <verify>
    <step>npm test -- email</step>
  </verify>
  <done>
    <criterion>Invalid emails rejected with clear error</criterion>
  </done>
  <commit>feat(user): add email validation to registration</commit>
</task>

**Context**:
- Preceding tasks: TASK-001 (UserService created)
- Key decisions: Use Zod for validation (DECISION-009)
- Patterns to follow: See existing validators in src/validators/

**Files to read**:
- src/services/UserService.ts: Where to add validation call
- src/validators/index.ts: Existing validation patterns

**Success criteria**:
- Invalid emails rejected with clear error

**Report back**:
- Task status
- Files modified
- Commit hash and message

---

3. Research Handoff

Request codebase investigation from researcher agent

Protocol:

## Research Request

**Question**: [Specific question to answer]

**Scope**:
- Directories: [where to look]
- File types: [what kinds of files]
- Depth: [how deep to go]

**Looking for**:
- [Specific pattern or information]
- [Specific pattern or information]

**Report format**:
- Findings summary
- Relevant file paths
- Recommendations

Example:

## Research Request

**Question**: How are API endpoints authenticated in this codebase?

**Scope**:
- Directories: src/api/, src/middleware/
- File types: *.ts
- Depth: All files in scope

**Looking for**:
- Authentication middleware
- JWT or session handling
- Authorization patterns

**Report format**:
- Findings summary
- Relevant file paths with line numbers
- Recommendation for adding new authenticated endpoint

---

4. Verification Handoff

Request verification from verifier agent

Protocol:

## Verification Request

**What to verify**:
- [Scope of verification]

**Checks to run**:
- [Automated check]
- [Automated check]

**Requirements to validate**:
- [FR-XXX]
- [FR-XXX]

**UAT scenarios**:
- [Scenario to test with user]

**Report format**:
- Pass/fail per check
- Requirements traceability
- UAT results
- Issues found (if any)
- Recommendation

---

5. Interview Handoff

Request requirements gathering from interviewer

Protocol:

## Interview Request

**Topic**: [What to explore]

**Initial areas**:
- [Area 1]
- [Area 2]

**Context from prior work**:
- [Relevant existing decisions]

**Depth**: [Light/Medium/Deep]

**Report format**:
- Exploration map
- Decisions made
- Requirements captured
- Conflicts identified

---

Handoff Best Practices

Include

• Specific task/question
• Relevant context only
• Success criteria
• Expected output format

Exclude

• Full workflow history
• Unrelated decisions
• Completed task details
• Large file contents (reference instead)

Format Consistency

Always structure handoffs with: 1. What: Task or question 2. Context: Essential background 3. Scope: Boundaries and constraints 4. Deliverable: Expected output

---

Receiving Results

From Executor

## Executor Result: TASK-XXX

**Status**: completed
**Files modified**:
- src/services/UserService.ts (added validation)
- src/validators/index.ts (new validateEmail)

**Commit**: a1b2c3d - feat(user): add email validation

**Verification**: All steps passed

**Notes**: Used existing validator pattern

From Researcher

## Research Result

**Question**: [original question]
**Confidence**: [High/Medium/Low]

**Findings**:
1. [Finding] - [file:line]
2. [Finding] - [file:line]

**Recommendations**:
- [Recommendation based on findings]

**Uncertainties**:
- [What couldn't be determined]

From Verifier

## Verification Result

**Overall**: PASS/FAIL

**Automated**:
- Build: PASS
- Tests: PASS (50/50)
- Lint: PASS

**Requirements**: 8/8 verified

**UAT**: PASS
- [Scenario 1]: PASS
- [Scenario 2]: PASS

**Recommendation**: Ready for completion

From Interviewer

## Interview Result

**Topic**: [topic explored]
**Coverage**: [X]%

**Exploration map**: [summary or reference to ITEM-XXX.md exploration section]

**Decisions captured**:
- DECISION-XXX: [summary]
- DECISION-YYY: [summary]

**Requirements identified**: [count]

**Conflicts found**: [count or "None"]

**Recommendation**: [Ready for PLAN / Continue exploring]

---

Error Handling in Handoffs

Agent Failure

## Agent Error: [agent]

**Task**: [what was requested]
**Error**: [what happened]
**State**: [what's preserved]

**Options**:
1. Retry with same agent
2. Try alternative agent
3. Manual intervention
4. Skip and continue

Incomplete Result

## Incomplete Result: [agent]

**Completed**: [what was done]
**Incomplete**: [what wasn't]
**Reason**: [why]

**Options**:
1. Continue with another agent
2. Accept partial result
3. Request completion