---

name: "workflow-state-machines" description: >- Use when designing, implementing, or debugging complex agentic workflows using state machine patterns. Keywords: state machine, durable execution, agent orchestration, graph-based agents, workflow checkpoints, C4 protocol.

Workflow State Machines

Overview

This skill provides a structured framework for building resilient, predictable agentic workflows using directed graph-based state machines. It emphasizes durable execution, explicit state transitions, and auditability to ensure complex agent interactions remain stable and debuggable.

When To Use

• When orchestrating multi-step, multi-agent processes that require durability and fault tolerance.
• When you need to integrate human-in-the-loop (HITL) checkpoints into long-running tasks.
• When debugging non-deterministic agent behavior through state history inspection.
• When enforcing KILO-KIT C4 Runtime Protocol stages as formal state transitions.

Core Concepts

Directed Graph Topologies

• Nodes: Represent distinct agent actions, tool executions, or decision points.
• Edges: Define the transition logic based on input, output, or conditions.
• Immutable State: Workflow state is treated as immutable, with transitions resulting in new state snapshots to ensure clean history.

Durable Execution & Checkpointing

• Workflows automatically persist the state after every transition.
• Resumption: Failed workflows can resume precisely from the last successful node (checkpoint) without re-executing completed prior computations.

Human-in-the-Loop (HITL) Interrupts

• Pause States: Workflows can enter a suspended state to await external input, human approval, or parameter adjustments.
• Manual Overrides: Operators can inject or edit state data while the workflow is paused before triggering the next transition.

Time-Travel Debugging

• All state changes are logged as events in a durable store.
• Replay: Developers can isolate a failing branch, modify inputs, and re-execute that specific subgraph to verify fixes without running the entire workflow from scratch.

Workflow

1. Define State Schema: Identify all necessary data attributes required for the entire lifecycle.
2. Decompose into Nodes: Break down the process into atomic, idempotent functions.
3. Map Edges: Implement conditional routing logic (e.g., success paths, failure paths, human-approval branches).
4. Configure Persistence: Set up a store for state snapshots and execution history.
5. Implement HITL Points: Add explicit breakpoints where the workflow yields control to the user.

Key Patterns

• LangGraph Integration: Use Graph-based definitions for complex stateful loops and branching.
• Temporal/Workflow Separation: Decouple task execution (activities) from orchestration logic (workflow).
• C4 Protocol Mapping:
  • Brainstorming Gate → Entry Node (Validation of Intent)
  • Workflow Execution → Graph Traversal
  • Verification Gate → Terminal Validation Node (Ensures success criteria)

Quality Gates

• Loop Prevention: Every cycle must have an exit condition or max-depth limit defined.
• Terminal States: Every graph MUST have defined success and failure termination nodes.
• Shared State Safety: Never share mutable state between parallel branches; always rely on state reducers or explicit state merging.
• Idempotency: All node-level functions must be idempotent to support safe retries.

Anti-patterns

• Unchecked Loops: Infinite recursion in agent planning steps.
• Implicit State: Relying on global variables instead of the explicit State Schema.
• Missing Terminal States: Workflows that hang without finishing or erroring out.
• Heavy Side-Effects in Nodes: Side effects that are difficult to rollback or reconcile during state replay.

References

• KILO-KIT Documentation
• C4 Runtime Protocol Specification
• LangGraph Patterns
• Durable Execution Principles